الانتقال إلى المحتوى الرئيسي
حزم SDK للخادم هي المكتبات الرسمية من Didit لخادم التطبيق لديك. تستدعي كل حزمة endpoints الخادم في مرجع API بطلبات واستجابات محددة الأنواع، وتتحقق من webhook التي ترسلها إليك Didit، وتتحقق من الرموز الخاصة بـDidit Authentication. لا يتضمن أي إصدار 1.0.1 الـendpointين الخاصين بـGoogle Wallet بعد: بدء التحقق عبر Google Wallet وإرسال استجابة المحفظة. تتضمن حزم Python وNode.js وJava وPHP وRuby و.NET كل endpoints الخادم الأخرى. تفتقر حزمة Go 1.0.1 إلى تسع endpoints أخرى، معظمها نقاط نهاية Travel Rule: راجع نقاط النهاية غير الموجودة في حزمة Go بعد. استخدم الحزم حيثما يحتوي كودك على مفتاح API من Didit: إنشاء جلسات التحقق، وقراءة القرارات، واستدعاء واجهات APIs المستقلة، وإدارة المستخدمين والشركات وسير العمل والحالات، وفحص المعاملات والمحافظ، وTravel Rule. في المتصفح أو تطبيق الجوال، استخدم بدلاً منها حزم web وnative: فهي تعرض مسار التحقق على مستخدمك، ولا تحتفظ بمفتاح API أبداً. تعرض صفحات endpoints الخادم في مرجع API، بما فيها صفحات خدمة Database Validation، عينة كود لكل حزمة SDK للخادم بجانب طلب cURL. تُعرض العينة بعد أن يتضمن أحدث إصدار من الحزمة الـendpoint وكل حقل ترسله العينة: يحصل كل endpoint أو حقل أُضيف إلى API على عينته مع الإصدار التالي من كل حزمة SDK. لا يتضمن أي إصدار 1.0.1 حقول الطلب الـ16 لخدمة Database Validation التي أُضيفت بعد إصداره، أي إصدار 1.0.1، مثل vin أو bank_account_number، لذلك لا تعرض صفحات الخدمة التي ترسلها سوى cURL.

​
التثبيت

​
الإعداد

تقرأ كل حزمة SDK متغيرات البيئة نفسها، لذلك يكون العميل الذي تنشئه دون أي خيارات جاهزاً للاستخدام. لا تملك بيئات Edge متغيرات بيئة للعملية: في هذه البيئات مرّر مفتاح API إلى عميل Node.js بوصفه خياراً. كل ما يمكنك ضبطه عبر متغيرات البيئة يمكنك تمريره إلى العميل أيضاً، إلى جانب عنوان URL الأساسي والمهلة وإعادة المحاولة والرؤوس الافتراضية وعميل HTTP الخاص بك. أنشئ عميلاً واحداً لكل عملية وشاركه، فهو يحتفظ بمجموعة اتصالات، ويمكن استخدامه بأمان من عدة خيوط أو مهام في وقت واحد. تستدعي طرق account (التسجيل البرمجي: التسجيل وتسجيل الدخول والمؤسسات والتطبيقات) العنوان https://apx.didit.me/auth/v2 ولا ترسل مفتاح API أبداً. سجّل الدخول عبر account.login، ثم مرّر رمز الوصول المُعاد إلى العميل بوصفه رمز الحساب.

​
ما تفعله كل حزمة SDK

  • الموارد والطرق. تتبع الاستدعاءات موارد الواجهة: client.<resource>.<method>(...)، مثل sessions.create أو sessions.retrieve_decision أو transactions.create، بصيغة الأحرف الخاصة بكل لغة. معرّفات المسار وسيطات موضعية، وجسم الطلب والاستعلام مجموعة واحدة من الحقول المسمّاة. تستخدم Python وNode.js وPHP وRuby أسماء الحقول الخاصة بالواجهة (workflow_id)، أما Go وJava و.NET فتستخدم صيغة لغتها (WorkflowID وworkflowId وWorkflowId).
  • القوائم. تتنقل طرق القوائم عبر كل النتائج نيابةً عنك (باستخدام limit وoffset في الخلفية)، وتعرض كذلك كل صفحة مع count وnext وprevious وresults. في Ruby، تمرّ auto_paging_each على كل الصفحات، وتقابل total_count وnext_url وprevious_url للصفحة الحقول count وnext وprevious في الواجهة.
  • الملفات. تقبل عمليات الرفع (صور المستندات وصور السيلفي وإثبات العنوان والاستيراد) مساراً أو بايتات أو تدفقاً. أما عمليات التنزيل (ملفات PDF للجلسات والتقارير) فتعيد بايتات أو تدفقاً، ولا تعيد JSON محللاً أبداً.
  • التوافق المستقبلي. يُحتفظ بأي حقل استجابة أو قيمة تعداد لا تعرفها نسخة الحزمة بعد، ويبقى قابلاً للقراءة، ولا يُعامَل كخطأ، فلا تكسر إضافة في واجهة برمجة التطبيقات تكاملاً منشوراً.
  • webhook. يتحقق webhooks.verify من الرأسين X-Signature-V2 وX-Signature ومن الطابع الزمني لعملية التسليم باستخدام سر webhook الخاص بك، ويعيد حدثاً مُنمَّطاً. يقبل قائمة أسرار أثناء تدوير أحدها. راجع webhook لمخطط التوقيع.
  • المصادقة. تتحقق مساعدة Authentication من رموز الوصول ورموز الهوية التي يوقّعها مُصدر Authentication لديك، وتستدعي endpoints الرموز والجلسات والتحقق المعزز الخاصة به. ولا تستخدم مفتاح API أبداً.

​
الأخطاء وإعادة المحاولات والمهلات

ترث جميع الأخطاء من DiditError. في Go، تُنفِّذ كل الأخطاء الواجهة didit.Error وكلٌّ منها من نوع مؤشر، مثل *didit.NotFoundError. تُسمّي Java وPHP و.NET الأخطاء بلاحقة Exception المعتادة لديها، وتكتب API على شكل Api: DiditException وApiStatusException وNotFoundException. تُعيد حزم SDK محاولة الطلب الفاشل حتى مرتين، مع تأخير متزايد أُسّياً يبدأ من 0.5 ثانية (عشوائية كاملة، بحد أقصى 8 ثوانٍ) مع مراعاة Retry-After. تُعاد محاولة طلبات GET وHEAD وPUT وDELETE عند أخطاء الاتصال وانتهاء المهلة و408 و429 و5xx. لا تُعاد محاولة طلبات POST وPATCH إلا عند 429 أو عندما يفشل الاتصال قبل إرسال الطلب، حتى لا تُنشئ إعادة المحاولة جلسة أو معاملة ثانية أبدًا. المهلة الافتراضية هي 60 ثانية. وتعرض كل استجابة أيضًا حالة HTTP الخام والرؤوس ومعرّف الطلب. راجع تحديد المعدل للاطلاع على الحدود التي تقف وراء 429.

​
الإصدارات والدعم

  • تتبع حزم SDK الإصدار الدلالي (Semantic Versioning)، مع قاعدة واحدة لتغييرات API. التغيير الذي يعكس واجهة Didit API يُصدر كإصدار فرعي، حتى عندما قد يكسر الكود ذي الأنواع (حقل تغيّر نوعه، أو حقل يمكن أن يصبح فارغًا الآن، أو نقطة نهاية أو حقل أو قيمة تعداد أُزيلت). فواجهة API تتصرف بهذه الطريقة بالفعل مع كل المستدعين، لذا لا يكون إصدار أقدم من الحزمة أكثر أمانًا. وتدرج ملاحظات الإصدار هذه التغييرات تحت عنوان “تغييرات API قد تكسر الكود ذي الأنواع”.
  • لا يُستخدم الإصدار الرئيسي إلا لتغيير في تصميم الحزمة نفسه: إعادة تسمية طريقة أو مورد أو إزالته بينما تحتفظ API به، أو تغيير في إعدادات العميل أو الأخطاء أو إعادة المحاولات أو الترقيم أو سلوك التحقق من webhook، أو إسقاط إصدار بيئة التشغيل. عندما تغادر نقطة نهاية واجهة API أو تُعاد تسمية طريقتها، تبقى الطريقة القديمة لإصدار فرعي واحد على الأقل، وتُوسَم بأنها مُهمَلة، حتى يستمر كودك في البناء بينما تنتقل إلى الجديدة. تحتفظ كل لغة برقم إصدار خاص بها: Node.js وPHP وRuby على 2.x والباقي على 1.x، لأن هذه اللغات الثلاث أصدرت تغيير API كإصدار رئيسي قبل تطبيق هذه القاعدة.
  • تُولَّد حزم SDK من عقد API المنشور (openapi-25.json وopenapi-auth.json)، وتُفحص طرق Didit Authentication الخاصة بها مقابل openapi-authentication.json. وتفحص الثلاثة كل يوم، لذا تصل نقطة نهاية أو حقل جديد ضمن إصدار منتظم لجميع حزم SDK السبع.
  • تدعم كل حزمة الحد الأدنى من بيئة التشغيل الوارد في الجدول وكل إصدار أحدث منه. وتعمل اختباراتها على الحد الأدنى وعلى كل إصدار أحدث، أو على كل إصدار دعم طويل الأمد (LTS) بالنسبة إلى Node.js وJava.
  • يسرد ملف CHANGELOG.md في كل مستودع التغييرات في كل إصدار.
  • أبلغ عن مشكلة أمنية بشكل خاص عبر التنبيهات الأمنية في مستودع حزمة SDK، أو عبر support@didit.me.
آخر تعديل في ٧ نوفمبر ٢٠٢٦