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

1) دور بوابة المطور

بوابة المطور هي «مكتب أمامي» للمتكاملين: الخدمة الذاتية (المفاتيح، الرموز، خطوط الويب، خطط التعريفة)، الشفافية (الحدود، الاستخدام، الفواتير)، الأمان (التناوب، التوقيعات)، سرعة التكامل (SDK، الوثائق، صندوق الرمل).

• تقليل TTI (وقت الاندماج) إلى ساعات.
• امنح التحكم في الوصول: من/ماذا/كم/متى.
• قلل الحمل على الدعم من خلال الأدوات الذاتية.

2) الإقامة والحسابات

التسجيل: البريد الإلكتروني + 2FA/SSO (SAML/OIDC) ؛ التحقق من صحة المجال (رمز DNS).
المنظمات والفرق: أدوار «المالك» و «المشرف» و «المطور» و «الفواتير» و «الأمان».
تعدد المستأجرين: ربط الطلبات بالمنظمات ؛ الوصول إلى البيانات - حسب المستأجر/البيئة.
KYC/B2B (بالجملة): بالنسبة للمؤسسة - الكيان القانوني، العقد، الحدود أعلاه.

3) التذييلات والائتمانات

أنواع التطبيقات: «server-to-server», «web», «mobile», «machine-to-machine», «webhook-consumer».

3. 1 واجهة برمجة التطبيقات (خادم إلى خادم، تكامل بسيط)

معرف 'key _ id' + secret 'key _ secret' (مرئي مرة واحدة).
ربط النطاقات التخطيط والمجموعات.
طلب توقيع (HMAC) و/أو "الإذن: ApiKey <رأس key_id>:<signature>'.

3. 2 OAuth2/OIDC (موصى به)

• وثائق اعتماد العملاء (الآلات).
• قانون الترخيص (+ PKCE) (بتفويض من المستخدم).
• Refresh Token (الوصول بدون اتصال بالإنترنت، تناوب RT).
• رمز الجهاز (تلفزيون/وحدات تحكم).

3. 3 mTLS (مستوى إضافي)

TLS المتبادلة عند الدخول ؛ وتنزيل الشهادات عن طريق البوابة ؛ ربط «بصمة الشهادة» بالطلب.

4) الرموز: الأنواع ودورة الحياة

• Short AT + long RT; RT - الدوران عند الاستخدام.
• الإلغاء حسب المفتاح/التطبيق/المنظمة.
• إعادة الإصدار مع تحديد النطاق/الحصص.

4. 1 شكل JWT (مثال)

json
{
"iss":"https://auth. example. com",
"sub":"app_123",
"aud":"https://api. example. com",
"exp":1730616000,
"iat":1730612400,
"scp":["wallet:read","bet:write"],
"org":"acme",
"kid":"jwks_2025_11",
"jti":"at_01HXY..."
}

يتم نشر المفاتيح العامة في JWKS ؛ التناوب بواسطة «طفل».

4. 2 رموز غير شفافة واستبطان

قم بتخزين «token _ store» (Redis/SQL) في خادم Auth.
الاستبطان: «نشط»، «نطاق»، «exp»، «عميل _ معرف»، «org»، «مستأجر».

5) النطاقات والأدوار وسياسات الوصول

تصف النطاقات العمليات («محفظة: اقرأ»، «محفظة: اكتب»، «تقرير: اقرأ»).
الأدوار مجمعة النطاقات («المطور»، «الفواتير»).
ABAC: سمات «org» و «المستأجر» و «المنطقة» و «البيئة».
السياسيون: «هذا المفتاح هو فقط» eu-west-1 «و» read'.
التصعيد: تتطلب الأساليب الحرجة نطاقات موسعة أو mTLS.

6) الحصص والحدود والتعريفات

حدود المعدل: RPS/RPM، انفجار.
الحصص: يوم/شهر، ائتمانات.
حسب المفتاح/التطبيق/المنظمة/المستأجر.
تُظهر البوابة الاستخدام، والرؤوس «X-RateLimit-» و «X-Conta-»، بالإضافة إلى توقعات الإفراط في العمل.
الفواتير: الارتباط بخطة، والقياس بالأحداث، والفواتير، وشبكات الفواتير.

7) إدارة الويب

تسجيل نقاط النهاية والأسرار وإصدارات الأحداث.
اختبار التسليم وإعادة التشغيل ؛ retry logs (2xx/4xx/5xx).
HMAC signations ('X-Signature'), 'X-Webhook-Id', deuplication, respect '410'.

8) التوثيق و SDK

OpenAPI/AsyncAPI مع التوليد التلقائي SDK.
كتاب الطبخ: أمثلة على الطلبات، إعادة الطباعة، الغباء، الاستعداد، خطافات الويب.
جرب الملعب (بمفاتيح الرمل).
نسخة Changelog وصفحة المنخفضات.

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

البيئات المعزولة: «sandbox» و «staging» و «production».
كيانات الاختبار (اللاعبون والمعاملات) والنصوص (الفوز/الخسارة، التأخير، 5xx، 429).
بذر البيانات من البوابة وبيئة إعادة الضبط.

10) أمن الأسرار وتخزينها

تجزئة الأسرار الرئيسية لواجهة برمجة التطبيقات (لا تخزن في نص واضح) ؛ أظهر المفتاح مرة واحدة.
المدير السري (KMS/HSM) لرموز التوقيع ؛ دوران مفاتيح «طفل».
IP allowist, geo-restrictions, ASN filters.
2FA/SSO، مفاتيح الأجهزة (WebAuthn).
الحماية من الإساءة: CAPTCHA عند إنشاء، ومضادات الروبوتات، وسرعة التسجيل.
الجذوع بدون أسرار PII ؛ التنقيح حسب الأنماط.

11) المراجعة والامتثال

سجل المراجعة: من أنشأ/شاهد/ألغى المفتاح، غير الويب، قام بتنزيل التقرير.
GDPR/DSAR - تنزيل وحذف بيانات التطبيق/المنظمة.
سياسات الاحتفاظ: TTL للسجلات، Legal Hold للحوادث.
شروط الاستخدام/الاستخدام العادل وقيود التصدير.

12) الإدارة والعمليات

استدعاء جماعي للرموز عن طريق الحادث/التسوية.
تعليق الطلب مؤقتاً (وقف التنفيذ) بسبب الاستئناف.
انقلاب المفتاح (وضع مفتاحين: «نشط/تالي»).
الاتصال بالحادث: صفحة الحالة، الرسائل البريدية، RSS/webhooks status.

13) بوابة UI/UX (شاشات رئيسية)

لوحة قياس المنظمة: الاستخدام/الأخطاء/SLO/الفواتير.
التطبيق: المفاتيح، الرموز، النطاقات، الحدود، خطوط الويب، البيئات.
سجلات توصيل Webhook مع مرشحات وزر إعادة تشغيل.
وحدة تحكم رمزية: مشكلة/استدعاء، تاريخ، أسباب.
Documentation and SDK, Quickstart, code mainples (copy-paste).
قسم «الهجرات والهجرات».

14) أمثلة على العقود والتشكيلات

14. 1 OpenAPI (مقتطفات)

yaml paths:
/v1/apps:
post:
summary: Create app security: [{ oauth2: [admin:apps. write] }]
responses:
'201': { description: Created }
/v1/apps/{app_id}/keys:
post:
summary: Create API key (shown once)
responses:
'201': { description: Created }
/v1/oauth2/token:
post:
summary: Token endpoint (CC/AC)
responses:
'200': { description: Access token }
/v1/tokens/revoke:
post:
summary: Revoke access/refresh token responses:
'204': { description: Revoked }

14. 2 رمز الاستبطان (إجابة)

json
{
"active": true,
"client_id": "app_123",
"scope": "wallet:read bet:write",
"org": "acme",
"exp": 1730616000,
"token_type": "access_token",
"jti": "at_01HXY..."
}

14. 3 السياسة الرئيسية (JSON)

json
{
"app_id":"app_123",
"plan":"pro-2025",
"scopes":["wallet:read","report:read"],
"limits":{"rps":50,"daily_requests":250000},
"regions":["eu-west-1"],
"ip_allow":["192. 0. 2. 0/24"]
}

15) عمليات التحديث والضمان

إصدارات واجهة برمجة التطبيقات الدلالية ('/v1 '، '/v2')، التوافق بين الإضافة وعدم الكسر.
تظهر البوابة: «ما عفا عليه الزمن»، حتى أي تاريخ، و «كيف تهاجر».
أدلة الهجرة، اختبار صندوق الرمل «v2»، مزدوج الكتابة/مزدوج القراءة حيثما أمكن ذلك.

16) إمكانية الرصد والإبلاغ

الاستخدام → الإيرادات: جداول الطلب/الائتمان/التراكب.
الأخطاء حسب الحالة/« خطأ _ رمز »، مخطط الكمون.
أدوات SLO: إمكانية الوصول و p95 لمقابض المفاتيح.
Export CSV/JSON, webooks of reports, API for analytics.

17) القوائم المرجعية

17. 1 السلامة

• 2FA/SSO، تأكيد المجال/البريد
• أظهر الأسرار مرة واحدة، تخزين التجزئة
• JWKS والتناوب الرئيسي، 'kid'
• mTLS (Ex)، IP allowist، مرشحات geo/ASN
• مكافحة الروبوت/مكافحة إساءة الاستخدام، الحد من معدل توليد المفتاح
• سجل مراجعة الإجراءات والوصول

17. 2 DX/على متن الطائرة

• بداية سريعة ≤ 5 دقائق
• SDK (TS/Py/Java/Go/.NET) بنفس السطح
• ملعب + مفاتيح رملية
• كتاب الطبخ: خطافات الويب، التثبيت، التراجع، الغباء
• الحدود/الخطط/صفحة التسعير
• أمثلة على عجينة النسخ

17. 3 عمليات

• استدعاء رمز جماعي، تعليق التطبيق
• صفحة الحادث/الحالة + الاشتراك
• DLQ/Replay لـ Webhooks
• تنبيهات تلقائية لاستنفاد الحصة القريبة
• التقارير والفواتير الشهرية

18) خطة التنفيذ (3 تكرارات)

• تسجيل org/الطلبات، وإصدار مفاتيح واجهة برمجة التطبيقات، OAuth2 وثائق اعتماد العملاء، والحدود الأساسية (RPS/الحصص)، وسجلات الطلبات والرسوم البيانية للاستخدام، والوثائق و SDK TS/Python، صندوق الرمل.

• JWT + JWKS، التناوب الرئيسي، Refresh Token + التناوب عند الاستخدام، 2FA/SSO الإلزامي، خطافات الويب (التوقيعات، الإعادات، قطع الأشجار، إعادة التشغيل)، كتائب الفواتير، التقارير والصادرات، الأدوار و ABAC.

• mTLS، أدوات الإدارة (الإلغاء الجماعي/التعليق)، التخفيضات والهجرات v2، Java/Go/.NET SDK، لوحات القيادة finops، GDPR/DSAR، Legal Hold، متقدمة لمكافحة الإساءة.

19) الأسئلة الشائعة الصغيرة

JWT أم غير شفاف ؟

JWT مريح دون سؤال خادم Auth (توقيع/« طفل »)، من الأسهل إلغاء المحتوى وإخفائه. كلاهما غالبًا ما يستخدم: JWT خارجيًا، معتم داخليًا مع الاستبطان.

كم من الوقت يعيش Access Token ؟

اختصار: 5-15 دقيقة للمخصص، 15-60 دقيقة للآلة. عوضت من قبل ميكانيكا التحديث.

كيف تدور المفاتيح بأمان ؟

ابق «نشطًا/تاليًا»، انشر كلاهما على JWKS، وقم بتبديل العملاء بواسطة «طفل»، ثم تذكر القديم.

المجموع

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