دليل تكامل DLT API
تكون موافقة DLT مفيدة فقط عندما يتمكن المطورون من إرسال الحمولة المعتمدة.
بعد موافقة DLT، ينتقل العمل العملي إلى حقول واجهة برمجة تطبيقات الموفر، ومعرفات القالب، ورؤوس المرسل، والأمر المتغير، وتقارير التسليم، وسلوك إعادة المحاولة، والتسجيل، ودليل التشغيل الذي يمكن للدعم فهمه.
يعد تكامل واجهة برمجة تطبيقات بوابة الرسائل القصيرة بعد موافقة DLT هو المكان الذي يلتقي فيه عمل امتثال الأعمال مع برامج الإنتاج. قد تعرض البوابة الرؤوس والقوالب المعتمدة، ولكن لا يزال التطبيق بحاجة إلى إرسال نمط الرسالة المعتمدة الدقيق من خلال واجهة برمجة التطبيقات (API) الخاصة بالموفر.
هذا الدليل مخصص للمطورين والمؤسسين وفرق العمليات التي تقوم بتوصيل OTPs وتنبيهات الطلبات والتذكيرات وإشعارات الخدمة إلى التطبيق بعد تسجيل DLT.
معيار تسليم واجهة برمجة التطبيقات (API).
إجابة سريعة
بعد موافقة DLT، قم ببناء خريطة الحمولة قبل كتابة كود الإنتاج.
يجب أن تتضمن عملية تسليم المطور ما يلي:
- حساب مزود خدمة الرسائل القصيرة ووثائق API.
- رأس المرسل المعتمد لكل رسالة.
- معرف قالب المحتوى لكل رسالة.
- معرف PE أو معرفات DLT الأخرى التي يطلبها الموفر.
- الترتيب المتغير وأمثلة القيمة المسموح بها.
- نموذج الطلب والاستجابة باستخدام بيانات وهمية.
- تفاصيل webhook تقرير التسليم.
- قواعد إعادة المحاولة والمهلة ومعالجة الفشل.
- تغيير التحكم في صياغة القالب والمعرفات.
ما يحتاجه المطورون بعد موافقة DLT
يحتاج المطورون إلى أكثر من مجرد لقطات شاشة. إنهم بحاجة إلى عقد حتمي.
| الإدخال | لماذا يهم |
|---|---|
| بيانات اعتماد المزود | مطلوب لمصادقة استدعاء API. قم بالتخزين بشكل آمن، وليس في المستندات. |
| رأس المرسل | يتحكم في هوية المرسل ويجب أن يتطابق مع أصول DLT المعتمدة. |
| معرف القالب | يربط نص الرسالة بقالب المحتوى المعتمد. |
| ترتيب متغير | يمنع القيم من الهبوط في العنصر النائب الخطأ. |
| معرفات PE أو الكيان | مطلوب من قبل بعض واجهات برمجة تطبيقات الموفر أو تعيينات DLT. |
| نقطة نهاية DLR | يتيح للنظام تلقي حالة التسليم وتفاصيل الفشل. |
| حالات الاختبار | يؤكد سلوك الإنتاج قبل حركة العملاء. |
إذا كان أي صف مفقودًا، فقد يعمل التكامل في وضع الحماية ولكنه يفشل أثناء الإرسال المباشر.
نموذج رسم خرائط الحمولة النافعة
تختلف واجهات برمجة تطبيقات الموفر، لذا لا تنسخ أسماء الحقول بشكل أعمى. قم بإنشاء خريطة حمولة خاصة بالمزود.
ورقة عمل حمولة DLT SMS API
| مفهوم | مثال لاسم الحقل | مثال على القيمة الوهمية | ملاحظات |
|---|---|---|---|
| المستلم | to | 919999999999 | استخدم أرقام الاختبار الحقيقية فقط في خطط الاختبار الخاصة. |
| المرسل | sender | ABCOTP | يجب أن يتطابق مع العنوان المعتمد. |
| القالب | template_id | TMP-XXXX-7754 | تخزين مع اسم حدث الرسالة. |
| المتغيرات | variables | ["123456", "5"] | يجب أن يتطابق الطلب مع العناصر النائبة للنموذج. |
| الكيان | pe_id | PE-XXXX-1420 | المتطلبات الخاصة بالمزود. |
| رد الاتصال | callback_url | /api/sms/dlr | التحقق من صحة التوقيعات إذا كان المزود يدعمها. |
لا تقم مطلقًا بإدخال مفاتيح واجهة برمجة التطبيقات (API) أو أسرار الموفر في التعليمات البرمجية المصدر. استخدم متغيرات البيئة أو التخزين السري المتوافق مع إعداد الاستضافة.
تقارير التسليم، وإعادة المحاولة، والسجلات
يجب ألا يتوقف تكامل الرسائل القصيرة بعد استجابة موفر الخدمة 200 OK. قد يقبل الموفر طلبًا ويعيد لاحقًا حالة التسليم الفاشلة.
DLR وقائمة التحقق من التعامل مع الفشل
- معرف رسالة موفر المتجر للارتباط.
- تلقي ردود الاتصال بتقرير التسليم حيثما يكون ذلك مدعومًا.
- التحقق من صحة رد الاتصال إذا قام الموفر بتوثيق تدفق التوقيع أو الرمز المميز.
- فصل فشل إرسال واجهة برمجة التطبيقات عن فشل تسليم الشبكة.
- تحديد قواعد إعادة المحاولة لأخطاء الموفر العابر.
- تجنب إعادة المحاولة بشكل أعمى عندما يكون القالب أو الرأس أو تعيين DLT غير صالح.
- قم بتسجيل سياق كافٍ لتصحيح الأخطاء دون تخزين قيم OTP الحساسة.
- عمليات التنبيه عندما تتجاوز معدلات الفشل الحد الأدنى.
بالنسبة لتدفقات OTP، كن حذرًا بشكل خاص عند إعادة المحاولة. يجب ألا يتلقى المستخدم عدة رموز صالحة معطلة دون أن يفهم التطبيق أي منها هو الحالي.
خطة الاختبار المباشر
قبل الإنتاج، اختبر كل قالب معتمد:
مراجعة الخرائط الثابتة
قارن بين قالب البوابة المعتمدة وورقة التسليم وحقول حمولة الموفر. يجب أن تصطف الأسماء.
إرسال تسيطر عليها
إرسال إلى أرقام الاختبار الداخلي فقط. تأكيد عرض المرسل ونص الرسالة والمتغيرات واستجابة الموفر.
فحص تقرير التسليم
تحقق من رد الاتصال وتعيين الحالة والسجلات ومعالجة الفشل.
تسليم Runbook
قم بتوثيق كيفية إضافة قالب جديد وتدوير مفاتيح الموفر وتصحيح الأخطاء وطلب الدعم.
أخطاء تكامل واجهة برمجة التطبيقات الشائعة
معرفات قالب الترميز الثابت بدون أسماء
يجب أن تكون المعرفات مرتبطة بأسماء أحداث الرسالة. بخلاف ذلك، لا أحد يعرف المعرف الذي ينتمي إلى تسجيل الدخول لمرة واحدة (OTP)، أو تحديث الطلب، أو تذكير الموعد.
تغيير الصياغة المعتمدة في الكود
يمكن للمطورين إضافة نسخة لتجربة مستخدم أفضل، ولكن يجب أن تتطابق الرسائل النصية القصيرة الخاصة بالإنتاج مع نمط القالب المعتمد.
تجاهل تقارير التسليم
طلبات واجهة برمجة التطبيقات (API) المقبولة ليست مماثلة للرسائل التي تم تسليمها. تتبع حالة تسليم المزود.
تسجيل الأسرار أو قيم OTP
يجب أن تساعد السجلات في تصحيح أخطاء التوجيه والحالة دون الكشف عن بيانات الاعتماد أو سجلات العملاء أو الرموز الحساسة.
الأسئلة الشائعة
هل يمكن دمج SMS API قبل موافقة DLT؟
يمكنك دعم عميل الموفر مسبقًا، ولكن يجب أن تستخدم حمولات الإنتاج الرؤوس المعتمدة ومعرفات القالب والأمر المتغير ومتطلبات الموفر الحالية.
ماذا يحدث إذا تغيرت صياغة القالب؟
تعامل مع الأمر على أنه تغيير في الإنتاج. قم بمراجعة تأثير DLT وتحديث تعيين الموفر وإعادة الاختبار وتحديث دليل التشغيل قبل الاستخدام المباشر.
هل يجب تخزين قيم OTP في سجلات الرسائل القصيرة؟
تجنب تخزين قيم OTP الحساسة في السجلات. معرفات الارتباط المخزنة وتفاصيل الحالة اللازمة لتصحيح الأخطاء دون تسريب الرموز.
هل يمكن لـ Shinka المساعدة في تكامل DLT API؟
نعم. يمكن لـ Shinka تعيين أصول DLT المعتمدة في حقول API الخاصة بالموفر، وإنشاء عينات من الحمولات، واختبار عمليات الإرسال، وتوثيق عملية التسليم النهائية.
