Yusuf Khalidd

Posted on Apr 23 • Originally published at apidog.com

كيفية استخدام Circle API: مدفوعات USDC، محافظ رقمية، وتحويلات مالية

تصدر Circle عملة USDC، ثاني أكبر عملة مستقرة من حيث القيمة السوقية، وتوفر مجموعة من واجهات برمجة التطبيقات (APIs) التي تتيح لك نقل الدولارات عبر السلسلة دون الحاجة إلى بناء بنية تحتية للحضانة أو الامتثال أو الخدمات المصرفية من الصفر. إذا كنت تريد تسوية دفعات الأسواق بسرعة، أو السماح للمستخدمين بالإيداع عبر البطاقة والسحب كـ USDC، أو نقل العملات المستقرة عبر ثماني سلاسل كتل بمكالمة واحدة، فإن واجهة برمجة تطبيقات Circle توفر لك المسار الأسرع للبدء. الوثائق الرسمية متوفرة على developers.circle.com، ومقدمة USDC على circle.com/en/usdc تستحق القراءة قبل البدء.

جرّب Apidog اليوم

في هذا الدليل ستجد خطوات عملية لتطوير تطبيقاتك عبر Circle: إنشاء الحساب، الفرق بين بيئة الاختبار والإنتاج، مصادقة Bearer Token، استخدام نقاط نهاية المدفوعات والمدفوعات الصادرة، إدارة محافظ Circle (Web3)، بروتوكول النقل عبر السلاسل (CCTP)، تشفير سر الكيان للمحافظ التي يتحكم فيها المطور، التكامل مع webhooks، التعامل مع الثباتية (idempotency)، والامتثال لـ KYB. ستجد أوامر curl وNode جاهزة للتنفيذ. للمهتمين بالمقارنة: راجع دليلنا حول أفضل واجهة برمجة تطبيقات (API) لربط العملات الورقية بالرقمية والعكس لمقارنة Circle بالبدائل.

💡ستحتاج إلى عميل API يتعامل مع REST وWeb3 بكفاءة أثناء النمذجة. Apidog يدعم مصادقة Bearer الخاصة بـ Circle، تبديل البيئات، إعادة اختبار الـ webhook ضمن مساحة عمل واحدة، بحيث يمكنك اختبار بيئة الاختبار والإنتاج جنبًا إلى جنب بدون إعادة كتابة الإعدادات.

ملخص سريع

واجهة برمجة تطبيقات Circle (Circle API) تنقسم إلى خدمات: Circle Payments (البطاقات، التحويلات البنكية، ACH)، Circle Mint (إصدار USDC للمؤسسات)، Circle Wallets / W3S (محافظ قابلة للبرمجة)، وCCTP (حرق-وسك USDC عبر السلاسل).
المصادقة تتم باستخدام Bearer Token. مفاتيح الاختبار تبدأ بـ TEST_API_KEY:، مفاتيح الإنتاج بـ LIVE_API_KEY:.
محافظ المطورين تتطلب نصًا مشفرًا (entity secret ciphertext) في كل عملية كتابة.
بروتوكول CCTP ينقل USDC عبر Ethereum، Arbitrum، Base، Optimism، Polygon PoS، Avalanche، Solana وغيرها، عبر عملية burn/mint موثوقة.
موافقة KYB مطلوبة للإنتاج؛ بيئة الاختبار متاحة لأي مطور.
استخدم مفتاح idempotency في كل طلب تغيير، وتحقق من توقيعات webhook عبر المفتاح العام من /notifications/publicKey/get.

ما هي واجهة برمجة تطبيقات Circle (Circle API)؟

Circle شركة مدفوعات منظمة تصدر USDC وتدير البنية التحتية اللازمة. واجهة Circle API تمنحك أربع خدمات أساسية:

Circle Payments API: تقبل البطاقات، ACH، SEPA، التحويلات البنكية، وتستقر كـ USDC في محفظة التاجر.
Circle Payouts API: ترسل تحويلات بنكية أو ACH من رصيد USDC لأي حساب مصرفي مضاف كمستفيد.
Circle Wallets (W3S): إنشاء محافظ حراسة أو محافظ يسيطر عليها المطور على سلاسل متعددة، مع إمكانيات توقيع المعاملات وإدارة الغاز.
CCTP: حرق USDC على السلسلة المصدر وسكه على وجهة أخرى بدون تغليف.

للمقارنة مع بنية Web3 العامة، راجع أفضل API لمحافظ العملات المشفرة ودليل كيفية استخدام Alchemy API.

المصادقة والإعداد

إنشاء حساب: ادخل console.circle.com وسجل حسابك.
البيئات: لديك بيئة اختبار (sandbox) مجانية وبيئة إنتاج (production) تتطلب KYB (مستندات تأسيس، معلومات المالك، حساب تمويل).
مفتاح API: من لوحة التحكم ← المطورين ← مفاتيح API. المفتاح يكون بصيغة:
- الاختبار: TEST_API_KEY:<id>:<secret>
- الإنتاج: LIVE_API_KEY:<id>:<secret>

تمرير المفتاح في الهيدر:

curl https://api-sandbox.circle.com/v1/ping \
  -H "Authorization: Bearer TEST_API_KEY:abc123:xyz789"

روابط API:
- Sandbox: https://api-sandbox.circle.com
- Production: https://api.circle.com
محافظ المطور (W3S): تحتاج إلى سر الكيان (entity secret) (سلسلة 32 بايت hex) تسجلها مرة واحدة في لوحة التحكم، وتستخدم كل مرة نصًا مشفرًا جديدًا (entitySecretCiphertext) مع المفتاح العام لـ Circle (تدوير تلقائي مع Node SDK).

تثبيت SDK:
```
npm install @circle-fin/developer-controlled-wallets
```

نقاط النهاية الأساسية

إنشاء مجموعة محافظ ومحفظة

إنشاء مجموعة محافظ (wallet set)، ثم إنشاء المحافظ داخل المجموعة.

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET,
});

const walletSet = await client.createWalletSet({ name: "payout-set-prod" });

const wallets = await client.createWallets({
  walletSetId: walletSet.data.walletSet.id,
  blockchains: ["ETH-SEPOLIA", "MATIC-AMOY"],
  count: 2,
});

console.log(wallets.data.wallets);

كل محفظة تعيد id وaddress وسلسلة الكتل. موّلها بـ USDC من صنبور الاختبار.

تحويل USDC من محفظة يتحكم فيها المطور

const transfer = await client.createTransaction({
  walletId: wallets.data.wallets[0].id,
  tokenId: "5797fbd6-3795-519d-84ca-ec4c5f80c3b1", // USDC on ETH-SEPOLIA
  destinationAddress: "0xRecipient...",
  amount: ["10.00"],
  fee: { type: "level", config: { feeLevel: "MEDIUM" } },
});

رد العملية يحتوي id لمتابعة حالة المعاملة عبر GET /v1/w3s/transactions/{id} أو عبر webhook.

قبول دفعة بطاقة وتسويتها كـ USDC

curl -X POST https://api-sandbox.circle.com/v1/payments \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "source": { "id": "card_4f1c...", "type": "card" },
    "amount": { "amount": "50.00", "currency": "USD" },
    "verification": "cvv",
    "description": "Order 1093",
    "encryptedData": "<PGP-encrypted card data>",
    "metadata": { "email": "buyer@example.com", "sessionId": "..." }
  }'

ملحوظة: بيانات البطاقة مشفرة بـ PGP باستخدام المفتاح العام لـ Circle (/v1/encryption/public). الرد يعيد id الدفعة، ويمكنك تتبع حالتها.

إرسال دفعة صادرة عبر تحويل بنكي أو ACH

curl -X POST https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destination": { "type": "wire", "id": "beneficiary_abc" },
    "amount": { "amount": "500.00", "currency": "USD" },
    "metadata": { "beneficiaryEmail": "vendor@example.com" }
  }'

نقل USDC عبر السلاسل باستخدام CCTP

CCTP بروتوكول عقود ذكية وليس REST endpoint. الخطوات العملية:

استدعي depositForBurn على عقد TokenMessenger في سلسلة المصدر.
راقب https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} حتى تصلك حالة complete وكائن attestation.
استدعي receiveMessage على عقد MessageTransmitter في السلسلة الوجهة مع بيانات الرسالة والتصديق.

ينتج USDC أصلي على السلسلة الوجهة بدون رموز مغلفة.

الـ Webhooks والثباتية (Idempotency)

Circle ترسل POST events (payments, payouts, transfers, chargebacks) إلى أي endpoint HTTPS تقوم بتسجيله عبر /v1/notifications/subscriptions.
كل webhook موقع بمفتاح ECDSA. احصل على المفتاح العام من /v1/notifications/publicKey/get وتحقق من رأس X-Circle-Signature.
كل endpoint قابل للتعديل يتطلب رأس Idempotency-Key (عادة UUID v4). إعادة محاولة نفس الطلب بنفس المفتاح تعيد نفس الرد بدون تكرار العملية.

الأخطاء الشائعة وحدود المعدل

401 Unauthorized: Bearer token ناقص أو خاطئ أو بيئة غير صحيحة.
400 Invalid entity secret ciphertext: النص المشفر أُعيد استخدامه أو تم تشفيره بمفتاح قديم.
429 Too Many Requests: حدود بيئة الاختبار تقريبًا 10 طلبات/ثانية/endpoint؛ في الإنتاج الحدود أعلى حسب الحجم.
Insufficient funds: المحفظة لا تملك USDC كافٍ أو فشلت البطاقة في فحص AVS/CVV.

للمزيد حول بنية البطاقات، راجع أفضل API لإصدار البطاقات.

تسعير واجهة برمجة تطبيقات Circle

بيئة الاختبار مجانية كليًا.
Circle Mint: سك/استرداد USDC للمؤسسات المؤهلة بدون رسوم.
Circle Payments: نسبة مئوية + رسوم ثابتة (عادة 2.9% + 30 سنت، تختلف حسب الحجم).
المدفوعات الصادرة (Wire/ACH): بضعة دولارات لكل معاملة.
W3S Wallets: التسعير لكل محفظة/معاملة (تواصل مع المبيعات).
CCTP: الخدمة مجانية، فقط تدفع رسوم الغاز للسلاسل.

اختبار واجهة برمجة تطبيقات Circle باستخدام Apidog

Circle API تشمل REST، webhooks موقعة، وعقود على السلسلة، لذلك أدوات مثل Postman لا تغطي كل السيناريوهات.
Apidog يستورد مواصفات OpenAPI مباشرة، ويدير رموز Bearer للبيئتين، ويمكنك كتابة نصوص اختبار تربط تدفقات البطاقات والمدفوعات والـ webhooks في تشغيل واحد.
حمل Apidog وحمّل مواصفات Circle من بوابة المطورين. استخدم الخادم الوهمي لمحاكاة webhooks ثم انتقل للإنتاج عند الجاهزية. لمساحات العمل المشتركة، سر الكيان يبقى آمنًا وتدير إصدارات المجموعة بجانب كودك.

الأسئلة الشائعة

هل أحتاج KYB لاختبار Circle API؟

لا، حسابات بيئة الاختبار متاحة لأي بريد إلكتروني. KYB فقط للإنتاج ونقل أموال حقيقية. بيئة الاختبار تقدم صنابير USDC لكل شبكة.

ما الفرق بين Circle Mint ومحافظ Circle؟

Circle Mint بوابة المؤسسات لتحويل الدولار إلى USDC والعكس. Circle Wallets/W3S بنية تحتية للمحافظ والمعاملات للمستخدم النهائي. معظم تطبيقات المستهلك تستخدم المحافظ؛ تطبيقات الخزانة تستخدم Mint. بديل التجزئة: راجع كيفية استخدام MoonPay API.

كيف يتجنب CCTP مخاطر الجسور؟

يتم حرق USDC الأصلي على السلسلة المصدر وسكه جديدًا على الوجهة بتصديق موقع من Circle، بدون مجمع سيولة يمكن استغلاله.

هل يمكن استخدام محافظ Circle بدون حفظ المفاتيح؟

نعم، المحافظ التي يتحكم فيها المستخدم في W3S تستخدم MPC والمصادقة بالـ PIN، والمستخدمون يوقعون عبر SDK. المحافظ التي يتحكم فيها المطور تعتمد على سر الكيان وتوقيع المعاملات في الخلفية.

هل تدعم Circle سلاسل Solana وغير EVM؟

نعم، W3S تدعم Solana وAptos وNEAR، والعديد من L2s. CCTP v2 يدعم Solana بالكامل منذ 2024.

كيف أدير سر الكيان بأمان؟

يمكن تدوير سر الكيان من لوحة التحكم؛ أنشئ سرًا جديدًا وسجله، واعمل بالنصين المشفرين الجديد والقديم فترة الانتقال. SDK يقرأ أي سر معرف في متغير البيئة، فيدعم النشر المتدحرج بسلاسة.

DEV Community