مفاتيح API والطلبات
العنوان الأساسي والإصدارات
كل الطلبات تُرسل إلى https://api.yasend.dev/v1/....
- داخل
/v1: التغييرات إضافية فقط: نقاط نهاية جديدة، وحقول اختيارية جديدة، وأنواع أحداث ورموز أخطاء جديدة. يجب أن يتجاهل كودك الحقول التي لا يعرفها. - التغييرات الكاسرة: تصدر في
/v2.
المصادقة
أرسل مفتاحك كرمز Bearer:
Authorization: Bearer ysk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
هناك نوعان من المفاتيح:
| المفتاح | طريقة إنشائه | صلاحياته |
|---|---|---|
| مفتاح الحساب | البوابة ← مفاتيح API، أو POST /v1/api-keys |
كل شيء في حسابك: كل الجلسات والويب هوك والمفاتيح والاستهلاك |
| مفتاح الجلسة | يُعاد مرة واحدة من POST /v1/sessions (أو POST /v1/api-keys مع sessionId) |
تلك الجلسة وحدها. مثالي لتطبيق أو خادم واحد يرسل من رقم واحد |
مع مفتاح الجلسة يمكنك حذف sessionId من طلبات الإرسال. وإذا كان في حسابك جلسة واحدة فقط، يمكنك
حذفه مع مفتاح الحساب أيضاً.
- التدوير: غيّر مفتاح الجلسة عبر
POST /v1/sessions/{id}/regenerate-key. - الإلغاء: ألغِ أي مفتاح عبر
DELETE /v1/api-keys/{id}. - التخزين: نخزّن المفاتيح مشفّرة بدالة hash، لذا لا يمكننا عرض مفتاح مرة أخرى. إذا فقدت مفتاحاً فأنشئ واحداً جديداً.
أبقِ المفاتيح على خادمك. لا تضعها أبداً في تطبيق جوال أو صفحة ويب، لأن أي شخص يملك المفتاح يستطيع الإرسال من رقمك.
الطلبات والاستجابات
- المحتوى: الطلبات والاستجابات بصيغة JSON (
Content-Type: application/json)، وأسماء الحقول بصيغةcamelCase. - الأوقات: بصيغة ISO 8601 وبتوقيت UTC.
- معرّف الطلب: كل استجابة تحمل الترويسة
X-Request-Id، ويظهر المعرّف نفسه كـrequestIdداخل كل خطأ. إذا أرسلتX-Request-Idخاصاً بك (8–64 محرفاً: أحرف وأرقام و.و_و:و-) يحتفظ به YASend، لتتبّع الطلب من طرف لطرف. اذكره عند التواصل مع الدعم. - الأخطاء: لها دائماً الشكل نفسه. راجع الأخطاء.
- إعادة محاولة الإرسال: استخدم الترويسة
Idempotency-Keyكي لا تتكرر الرسالة أبداً. راجع إرسال الرسائل.
التوافق مع YASend المستضاف ذاتياً
الواجهة الأصلية المستضافة ذاتياً تعمل أيضاً:
- مسارات
/api/...؛ - الترويسة
X-Api-Key؛ /api/send-message.
يمكن للتكاملات الحالية الانتقال إلى YASend Cloud بتغيير العنوان الأساسي والمفتاح فقط. أما التكاملات
الجديدة فيجب أن تستخدم /v1.