Fiatside

Developers

الأوامر وعدم التكرار

إنشاء أمر يثبت السعر ويعين عنوان إيداع. هو المكان الوحيد الذي يمكن أن يؤدي فيه خطأ في التكامل إلى تحريك الأموال: التكرارية ليست رفاهية هناك.

عقد منشور، غير مفتوح بعد

هذه النقاط الطرفية غير معروضة اليوم. تم توثيقها لتتمكن من بناء تكاملك مسبقًا؛ شكلها محدد، وأي تغيير جذري سيمر عبر إصدار جديد وإدخال في سجل التغييرات.

POST/api/v1/ordersPublished contract, not open

إنشاء أمر

يقفل السعر ويُرجع عنوان إيداع مخصص. يحمل الأمر التفصيل كما هو مقفل: إنه قابل لإعادة التشغيل، مما يتيح لك إعادة بناء السعر الدقيق المطبق حتى بعد أشهر. رأس Idempotency-Key مطلوب.

المصادقة: Authorization: Bearer … انظر المصادقة

المعلمات

المعلمات
الحقلالنوعالوصف
quoteIdمطلوبstringمعرّف الاقتباس المقبول.
beneficiaryمطلوبobjectالحقول التي يفرضها مخطط القناة. يجب أن يتطابق الاسم مع الهوية الموثقة: لا دفعات لأطراف ثالثة.
networkIdمطلوبstringالشبكة التي سيتم إرسال الإيداع عليها. تحدد العنوان الذي تم إرجاعه، وعلى بعض الشبكات، المذكرة الإلزامية.
الطلبbash
curl -sS -X POST https://fiatside.com/api/v1/orders \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "qt_01J9Z...",
    "networkId": "tron",
    "beneficiary": {
      "railId": "sepa_instant",
      "beneficiaryName": "Camille Dupont",
      "iban": "FR7630001007941234567890185"
    }
  }'
الاستجابة — العقد المنشورjson
{
  "reference": "K7Q4-M2XB",
  "state": "AWAITING_DEPOSIT",
  "deposit": {
    "asset": "USDT",
    "network": "tron",
    "address": "T...",
    "memo": null,
    "amountBase": "1000000000",
    "expiresAt": "2026-09-02T12:41:00Z"
  },
  "payout": { "railId": "sepa_instant", "netMinor": 91228, "currency": "EUR" },
  "rateLock": { "midRate": "0.92168430", "lockedUntil": "2026-09-02T12:41:00Z" }
}
  • المذكرة تكون فارغة على معظم الشبكات وإلزامية على XRP و Stellar و TON. حذفها هناك يفقد الأموال: تعامل مع الحقل كإلزامي بمجرد أن يكون غير فارغ.

الأخطاء المحتملة: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. الفهرس الكامل

GET/api/v1/orders/{reference}Published contract, not open

قراءة أمر

الحالة الحالية وسجل التحولات المختوم بالطوابع الزمنية. السجل هو مصدر الحقيقة: فهو للإلحاق فقط، ولا يُعاد كتابته أبدًا، وهو ما يجيب على سؤال "لماذا انتقل طلبي إلى تلك الحالة في ذلك الوقت".

المصادقة: Authorization: Bearer … انظر المصادقة

الطلبbash
curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'
الاستجابة — العقد المنشورjson
{
  "reference": "K7Q4-M2XB",
  "state": "COMPLETED",
  "transitions": [
    { "at": "2026-09-02T12:11:04Z", "from": "QUOTE_LOCKED",     "to": "AWAITING_DEPOSIT" },
    { "at": "2026-09-02T12:19:52Z", "from": "AWAITING_DEPOSIT", "to": "DEPOSIT_DETECTED" },
    { "at": "2026-09-02T12:21:10Z", "from": "CONFIRMING",       "to": "DEPOSIT_CONFIRMED" },
    { "at": "2026-09-02T12:21:44Z", "from": "PAYOUT_QUEUED",    "to": "PAYOUT_SENT" },
    { "at": "2026-09-02T12:22:03Z", "from": "PAYOUT_SENT",      "to": "COMPLETED" }
  ]
}

الأخطاء المحتملة: unauthorized, not_found. الفهرس الكامل

01

التكرارية

طلب إنشاء ينتهي بوقت انتهاء على الشبكة لا يخبرك ما إذا تم إنشاء الأمر. بدون مفتاح تكرارية لديك فقط خياران سيئان: إعادة المحاولة والمخاطرة بأمرين، أو عدم إعادة المحاولة والمخاطرة بعدم وجود أي أمر.

الترويسةhttp
Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33

مفتاح واحد لكل نية

المفتاح يحدد نية "إنشاء هذا الأمر"، وليس طلب HTTP. معرّف فريد من جانبك: معرّف سلة، UUID تم إنشاؤه قبل الاستدعاء، وليس عدادًا أبدًا.

إعادة الإرسال تعيد الاستجابة الأصلية

إعادة إرسال نفس المفتاح مع نفس الجسم يعيد استجابة الطلب الأول، مع نفس حالة HTTP. هذا ما يجعل إعادة المحاولة آمنة، حتى بعد انتهاء المهلة.

نفس المفتاح، نص مختلف: تعارض

الاستجابة هي تعارض صريح. إذا تغير المحتوى، يجب أن يتغير المفتاح: وإلا فلا يمكن لأحد أن يعرف أي من الأمرين يجب إعادة تشغيله.

احتفاظ لمدة 24 ساعة

بعد ذلك يُنسى المفتاح وتؤدي إعادة التشغيل إلى إنشاء أمر جديد. أعد المحاولة خلال النافذة، أو تحقق من الحالة عبر نقطة نهاية القراءة.

02

المذكرة، على الشبكات التي تتطلبها

على XRP وStellar وTON، عنوان الإيداع غير كافٍ: معرّف إضافي يحدد المستلم النهائي. وهو السبب الأكثر تكلفة للحوادث في تكامل التحويل إلى الخارج.

إيداع بدون مذكرته هو إيداع ضائع

حقل المذكرة فارغ على معظم الشبكات وغير فارغ على تلك التي تتطلبه. تعامل معه كإلزامي بمجرد أن يكون غير فارغ، واعرضه بنفس أهمية العنوان. الإيداع الذي يصل بدون مذكرته على عنوان مشترك يتطلب استردادًا يدويًا، وهو ما لا ينجح دائمًا.

03

حالات الأمر

الحالات أدناه هي التي يمكن لتكاملك ملاحظتها. التحولات موقوتة ومُلحقة، ولا يُعاد كتابتها أبدًا: التاريخ يجيب على سؤال “لماذا انتقل أمري إلى تلك الحالة في ذلك الوقت”.

حالات الأمر
الحالةمعناها
QUOTE_LOCKEDالسعر مجمد. ينتظر الأمر تفاصيل المستفيد أو التحقق من الهوية.
AWAITING_DEPOSITتم تعيين عنوان الإيداع ونافذة الإيداع مفتوحة. هذه هي اللحظة الوحيدة لإرسال الأموال.
DEPOSIT_DETECTEDتُرى معاملة واردة على الشبكة، غير مؤكدة بعد. طمئن المستخدم، ولا تسلم شيئًا.
CONFIRMINGتتراكم التأكيدات. العدد المطلوب يعتمد على الشبكة، وليس على المبلغ.
DEPOSIT_CONFIRMEDالإيداع مؤمن. تُقيَّم قواعد الامتثال وإعادة التسعير من هنا.
UNDERPAIDالمبلغ المستلم أقل من المتوقع بما يتجاوز التسامح. ثلاث نتائج: إضافة مبلغ، أو المتابعة بالمبلغ المستلم، أو استرداد المبلغ.
OVERPAIDالمبلغ المستلم يتجاوز المتوقع. يبقى المبلغ الأولي بسعر الصرف المثبت، ويُعالَج الفائض بشكل منفصل.
PAYOUT_QUEUEDالتحويل في قائمة الانتظار. تضمن قائمة الانتظار إرسال الدفعة مرة واحدة فقط، حتى لو اشتعلت عدة عمليات بالتوازي.
PAYOUT_SENTغادر التحويل عبر قناة الدفع. الإرسال لا يعني الاستلام: التأخير النهائي يعتمد على البنك المستفيد.
COMPLETEDتم تأكيد التسوية من قبل قناة الدفع. حالة نهائية.
PAYOUT_FAILEDرفضت قناة الدفع التحويل أو أعادته. لا توجد إعادة محاولة تلقائية: السبب دائمًا تقريبًا في التفاصيل.
REFUNDEDأعيدت الأموال إلى العنوان المصدر، بعد خصم رسوم الشبكة. حالة نهائية.