التكامل التقني

بوابة المطورين

عقود API والمصادقة وwebhooks والتكرار الآمن وإدارة الأخطاء والمبادئ التشغيلية لتكاملات المؤسسات.

العقد أولاً ثم التنفيذ

يتم تحديد نماذج البيانات وحدود الصلاحيات وسلوك الفشل وقواعد إعادة المحاولة قبل التنفيذ.

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

REST API
نقاط نهاية موجهة للموارد وأكواد متسقة وإصدارات وتوافق خلفي.

WebSocket
دورة الاتصال وإعادة الاتصال وترتيب الأحداث الفورية.

Webhooks
إشعارات موقعة وإعادة المحاولة ومعرفات التسليم والمعالجة الآمنة من التكرار.

Idempotency
معالجة آمنة للطلبات المتكررة في العمليات الحرجة.

نموذج الأخطاء
أكواد قابلة للمعالجة ومعرفات ارتباط وقابلية تتبع.

حدود المعدل
حصص وbackoff وإعادة محاولة مضبوطة.

قابلية المراقبة
سجلات ومقاييس وتتبع ومعرفات أحداث.

مثال عقد API

الأمثلة توضح نمط التكامل؛ نقاط النهاية الفعلية يحددها عقد المشروع.

POST /v1/transactions
Idempotency-Key: <unique-key>
Authorization: Bearer <token>

{
  "reference": "client-reference",
  "asset": "ASSET",
  "amount": "100.00"
}

ناقش النطاق التقني

عقد API تمثيلي

يجب ألا يكون سلوك التكامل غامضاً.

النموذج التالي تمثيلي؛ يتم تحديد نقاط النهاية والمخططات الفعلية لكل مشروع.

REQUEST

POST /v1/transactions
Authorization: Bearer <token>
Idempotency-Key: <unique-key>

{
  "reference": "client-reference",
  "asset": "ASSET",
  "amount": "100.00"
}

ERROR MODEL

{
  "error": {
    "code": "POLICY_REJECTED",
    "message": "Request rejected",
    "request_id": "req_..."
  }
}

WEBHOOK

event: transaction.updated
signature: <signed-header>
delivery_id: <unique-id>

verify → persist → process → 2xx