وصلات مركزي التكامل وواجهة برمجة التطبيقات

1) دور مكتب الأمم المتحدة المركزي في بوروندي ومجال مسؤوليته

• وتوحيد البروتوكولات والأشكال ؛
• وضمان الموثوقية (إعادة التصوير، وقوائم الانتظار، وسياسات المهلة، وقاطع الدوائر) ؛
• ضمان الأمن (mTLS، OAuth2، JWT، HMAC، IP-allowist) ؛
• ومركزية إمكانية الرصد (السجلات والمقاييس والآثار) ؛
• تبسيط مزود التغيير (المحولات + رسم الخرائط الميدانية)
• إعطاء عقود ثابتة لفرق المنتجات.

2) مبادئ التصميم

العقود المتسقة: مفردة/أحداث/مخطط صارم ونسخة صارمة.
الخصوصية - طلب المفاتيح، والتفريغ، والإعادة الآمنة.
الافتراضي آمن من الفشل: المهلة، التراجع، سياسات قاطع الدائرة.
إمكانية الرصد كدالة: كل شيء قابل للقياس ويمكن تتبعه.
فصل التكامل عن المجال: المحولات لا «تعرف» منطق الأعمال للنواة.
قيمة الحدث: نشر/اشترك في العمليات غير المتزامنة.
الإصدار: تتعاقد SemVer وتدير الاكتئاب.

3) الهندسة المعمارية الرفيعة المستوى

واجهة برمجة التطبيقات البوابة: المصادقة، حدود الأسعار، إطلاقات الكناري، WAF.
المنسق/الراوتر: التوجيه من قبل مقدمي الخدمة، الأولويات، الفشل، التوجيه الذكي.
محولات المزود: REST/gRPC/GraphQL/WebSocket، رسم الخرائط الميدانية، المخابئ المحلية.
حافلة EDA (Kafka/RabbitMQ/NATS): الأحداث «تم إنشاء الدفع»، «تم تمرير KYC»، «بدأت جلسة اللعبة».
خدمة العقود/المخططات: سجل المخطط لشركة JSON/Avro/Protobuf.
تكامل دولة التخزين: idempotence keys, corrence, status.
إمكانية الملاحظة: Prometheus/OTel + لوحات القيادة والتنبيهات.
DevPortal: أدلة التكامل، OpenAPI/Protobuf، أمثلة، صناديق الرمل.

4) عقود ومخططات البيانات

مخططات صارمة (مخطط JSON/Avro/Protobuf)، التحقق الإلزامي من المدخلات/المخرجات.
سجل المخططات مع سياسة متوافقة مع الخلف.
اتفاقيات الخطأ الواضح (نموذج رمز/تفصيل موحد).

5) البروتوكولات المدعومة

REST (OpenAPI): متعدد الاستخدامات وسهل التوثيق.
gRPC: أداء عالي للاتصالات الداخلية.
الرسم البياني QL: عند الحاجة إلى عينات مجمعة.
الحواسيب الشبكية: أحداث للنظم الخارجية ؛ توقيع HMAC، إعادة التسليم.
SSE/WebSocket: بث مباشر للحدث (حالات حية، معاملات).

6) الأمن والوصول

MTLS بين الخدمات الداخلية.
OAuth2/OIDC للعملاء الخارجيين، رموز قصيرة العمر.
JWT for Service Federation of Identities; مطالبات مراجعة الحسابات.
توقيعات HMAC لخطابات الويب/التراكمات الحرجة.
IP-allowist, WAF, RASP, anti-bot filters.
الإدارة السرية (KMS/HSM)، تناوب المفتاح، تقسيم المعرفة.
GDPR/PCI DSS: تقليل البيانات الشخصية والبطاقات، الترميز.

7) التوجيه والتنسيق

التوجيه القائم على السياسة العامة: حسب الجغرافيا والعملة ومقاييس الفشل، مزود جيش تحرير السودان.
الفشل: تسلسل PSP/مزود، التحلل التلقائي.
قاطع الدائرة: فروع سريعة التحمل للخطأ للأخطاء المتكررة.
Bulkhead: العزل حسب المزود/المستأجر/تجمع الخيوط.
ملحمة/تنسيق العمليات الطويلة (التسجيل → إيداع → شركة KYC).

8) الفراغ ومرة واحدة بالضبط (حقيقي بقدر ما يحصل)

Idempotency-Key + status/response cache.
تفريغ حدث الحافلة (مفتاح الارتباط).
التخزين «الطلبات المشاهدة» مع TTL.

http
POST /payments
Idempotency-Key: 3d8c1a4f-7f0e-4a2a-9e5a-2b8d3e7e2c11
Content-Type: application/json

json
{
"tenantId": "eu-casino-12",
"userId": "u-9812",
"currency": "EUR",
"amount": 50. 00,
"method": "card",
"metadata": {"orderId": "ORD-2025-1105-001"}
}

سيوفر HUB النتيجة ويعيد نفس الاستجابة عند الإعادة.

9) قوائم الانتظار وحافلة الأحداث

Kafka/NATS/RabbitMQ للخطوات غير المتزامنة: نتائج KYC، وحالات الدفع، وتوازن مزود اللعبة.
الموضوعات التي تحتوي على مفاتيح العضوية هي «معرف المستأجر» أو «معرف المستخدم» أو «معرف المزود».
الاحتفاظ و DLQ (حرف ميت) مع إعادة تقديم تلقائي بعد الإصلاح.
نمط Outbox في خدمات النواة لنشر الأحداث المضمونة.

10) الحرث والتوافق

SemVer على العقود: "v1"، "v1. 1 '،' v2 '.
بالتوازي مع وجود نسختين صغيرتين، جدول زمني واضح للاكتئاب.
محولات الهجرة (مخططات ميدانية مؤقتة) للانتقال السلس.

11) قابلية الملاحظة والموثوقية

المقاييس: زمن الكمون p50/p95/p99، معدل الخطأ، الإنتاجية، نسبة النجاح من قبل مقدمي الخدمة، وقت تأكيد الحدث، «الوقت إلى المحفظة».
التعقب (OTel): «تتبع إلى طرف »/« امتداد _ معرف» من واجهة برمجة التطبيقات إلى استجابة المزود.
الجذوع: منظم، مع ارتباط «طلب _ معرف»، قناع PII/PAN.
SLO: على سبيل المثال، 99. 9٪ معدل النجاح <1. 5s للمسارات الحرجة.
التنبيهات: حسب ميزانية خطأ SLO، نمو DLQ، إعادة/مهلة التشويه.

12) صناديق الرمل ودوائر الاختبار

صندوق الرمل لكل مزود: الإصلاحات، محاكيات الإجابة، إصدار البيانات.
اختبار العقود (Pact/Buf) والتوليد الذاتي لـ SDK.
ملفات تعريف التحميل وفقًا لسيناريوهات «ذروة البطولات» و «موجات الدفع».

13) فئات التكامل (مثال على iGaming)

المدفوعات/عمليات السحب: PSP، الخدمات المصرفية A2A/Open، بوابات التشفير.
KYC/AML/Risk: التحقق من الهوية/العنوان، وقوائم العقوبات، والتسجيل السلوكي.
مزودو/مجمعو الألعاب: إطلاق الجلسة، ورموز اللعبة، ومجموعات العودة.
الاتصالات: البريد الإلكتروني/الرسائل القصيرة/الدفع/الرسائل.
التحليلات/BI: بث الحدث والتجمعات.
الاحتيال/أجهزة الشحن: مراكز النزاع، التنبيهات.

14) تعدد الإيجارات والمناطق

عزل TenantId: مفاتيح التشفير، والحصص، والحدود، وحمامات السباحة.
الشحن الجغرافي: التوجيه إلى أقرب برنامج عمل إقليمي/منطقة، مع مراعاة القواعد المحلية.
موفر/طرق الدفع المحلية: القائمة حسب الولاية القضائية ومستويات KYC.

15) الأداء والتخزين المؤقت

Token cache (PSP/KYC)، استجابات البيانات الوصفية للمزود (TTL).
تجميع الوصلات وإعادة استخدام جلسات TLS.
Async I/O لـ RPS عالية ؛ التزحلق في المحولات.
حدود الأسعار على محيط العميل والمزود.

16) سيناريوهات من البداية إلى النهاية (أمثلة)

16. 1 إيداع (بطاقة)

1. "POST/payments' → Orchestrator → PSP # 1.
2. Timeout 2s ؛ при '5xx/timeout' - إعادة المحاولة с التراجع ؛ أثناء التدهور - PSP # 2.
3. دفع الحدث. '→ الرصيد الأساسي المأذون به → BI/مكافحة الغش.

16. 2 KYC

1. محول «POST/kyc/submission» → KYC.
2. async: webhook 'kyc. ' في حالة الفشل - تكرار التسليم (حتى مرات شمالا).
3. الحدث 'kyc. تم التحقق منه "في الحافلة.

16. 3 جلسة اللعبة

1. «POST/games/session» → مجمع محول → جلسة رمز.
2. وتثبت مجموعات النتائج/الرهانات → مكتب الأمم المتحدة المركزي في بوروندي صحة التوقيع والخصوصية.
3. لعبة الحدث. مستديرة. يذهب إلى حساب المدفوعات والإبلاغ.

17) الأخطاء وتنسيق الاستجابة الموحدة

Коды: 'التكامل _ TIMEOUT',' SECURITY _ SIGNATURE _ INVALID ',' CONTRACT _ VALIDATION _ FAILED '.

json
{
"code": "PROVIDER_UNAVAILABLE",
"message": "Primary PSP degraded, switched to fallback",
"correlationId": "9f8e1b6a-1c2d-4b4e-9d31-91c6bc31c1d4",
"provider": "psp-1",
"hint": "Retry allowed; idempotency key required"
}

18) خطافات الويب الآمنة: وقع وكرر

X-Signature: sha256=hex(hmac_sha256(secret, body + timestamp))
X-Timestamp: 1730812800

تحقق من وقت الانجراف وقبول الإشعارات الجديدة فقط. يتكرر - بشكل كبير إلى N، ثم في DLQ.

19) إدارة التغيير والإصدارات

محولات الكناري (1-5٪ من حركة المرور)، تتميز بأعلام لكل مستأجر.
الإصدارات المتوافقة مع الخلف: المحولات أولاً، ثم العقود.
CAB/CRQ للمزودين الخارجيين، يتم نشر النوافذ بشكل متسق SLA.

20) جيش تحرير السودان/جيش تحرير السودان/مكتب الشؤون القانونية

مزود SLA: وقت التشغيل ≥ 99. 9٪، خطابات الويب ack ≤ 3c، إنهاء الدفع ≤ 30c (p95).
SLO HUB: p95 <1. 5c إلى نقاط النهاية الحرجة، معدل الخطأ <0. 3%.
OLA بالداخل: حدود قائمة الانتظار، ميزانية إعادة الدفع، الحد الأقصى لأوقات DLQ.

21) كتالوج التكامل و DevPortal

صفحات المزود: الحالات، إصدارات المحول، المتطلبات الميدانية، القوائم المرجعية.
SDK autogen (OpenAPI/gRPC)، أمثلة، مجموعات ساعي البريد، خوادم وهمية.
زر «اختبر في Sandbox» وخطوط تكامل CI.

22) السلامة والامتثال

إصدار PII في جذوع الأشجار، وتشفير حقول الراحة، وحقول PAN فقط في شكل رمزي.
RBAC/ABAC لأفرقة المشغلين، أقل مبدأ امتياز.
سجلات الموافقة (GDPR)، الحق في حذف/منفذ.
مخاطر البائعين وإدارة شؤون الإعلام لعمليات التكامل الجديدة.

23) خطة التنفيذ (مقياس → MVP)

أفضل لاعب (0-2 أشهر): بوابة، 1-2 PSP، 1 KYC، مجمع ألعاب 1، مقاييس خط الأساس، الخصوصية، DLQ.
المرحلة 2 (3-4 أشهر): حافلة EDA، DevPortal، اختبارات العقد، التوجيه الاحتياطي، توقيع خطابات الويب.
المرحلة 3 (5-6 أشهر): مجموعات مزودة بتحويل جغرافي، وتوجيه ذكي عبر جيش تحرير السودان، وتنبيهات SLO/تنبيهات موسعة، و SDK autogen، و canary.

24) قائمة مرجعية قبل البيع

العقود في قلم المحكمة، اجتازت اختبارات التوافق.
يتم وضع سياسات المهلة/الاسترجاع/الكسر وتغطيتها باختبارات e2e.
IdempotencyKey مدرج في POST/PUT الحاسمة.
يتم التحقق من توقيعات خطافات الويب، ويتم تكوين الإعادة، ويتم مراقبة DLQ.
P95/p99 ومقاييس معدل الخطأ تتوافق مع SLO، التنبيهات متصلة.
أسرار في نظام إدارة كوسوفو، اختبار التناوب ؛ IP-allowist/WAF نشطة.
نشر كتب التشغيل/كتب اللعب أثناء الطلب.
DevPortal والصناديق الرملية متاحة للشركاء، ويتم توثيق الإصدارات.

موجز

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