واجهة برمجية
بوابة api.corbit.sa
https://api.corbit.saواجهة واحدة للرسائل القصيرة وواتساب للأعمال ونواة SMPP: إرسال فردي وجماعي، الرصيد، أسماء المرسل، حالة التسليم، القوالب، والأرشيف. متوافقة مع صيغ أكثر من 18 منصة رسائل سعودية، فالربط السابق يعمل بتغيير النطاق فقط.
عندك ربط سابق مع شركة رسائل أخرى؟
البوابة تتعرّف تلقائيًا على صيغة الطلب وتردّ بالصيغة نفسها التي يتوقعها نظامك. استبدل نطاق مزوّدك السابق بـ api.corbit.sa في إعدادات نظامك مع مفتاح API من حسابك في كوربت، وسيعمل الإرسال والرصيد وأسماء المرسل وحالة الرسائل كما هي: نفس المتغيرات، نفس التشفير، نفس طريقة الربط، بلا تغيير في كودك أو مكتباتك.
ابدأ في أربع خطوات
- 1أنشئ حسابًا في sms.corbit.sa وفعّل اسم مرسل معتمدًا.
- 2من الإعدادات ← مفاتيح الربط API أنشئ مفتاحًا، وأرسله في ترويسة Authorization: Bearer مع كل طلب.
- 3أرسل رسالة تجريبية بـ POST /api/v1/send، وستعود بمعرّف الرسالة.
- 4تابع التسليم بـ message-status وmessage-report، واقرأ الرصيد والحدّ من /gateway/v1/usage.
مثال إرسال رسالة واحدة
curl -X POST https://api.corbit.sa/api/v1/send \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "senderName": "YOUR_SENDER", "number": "9665XXXXXXXX", "messageBody": "Your code is 4821", "sendAtOption": "NOW" }'الرقم بالصيغة الدولية أرقامًا فقط (8–15 رقمًا)، والنص حتى 1600 حرف. التوثيق الكامل يعرض الأمثلة بـ 25 لغة ومكتبة.
المصادقة حسب القناة
| القناة | المفتاح | أين يوضع |
|---|---|---|
| الرسائل القصيرة وخدمات البوابة | مفتاح API من حسابك في sms.corbit.sa | Authorization: Bearer |
| واتساب للأعمال | مفتاح واتساب sk_live_… | Authorization: Bearer |
| نواة المنصة (Core) | ApiKey وClientId | معاملات الاستعلام أو جسم JSON |
النقاط المتاحة
| النقطة | الوظيفة |
|---|---|
| POST /api/v1/send | إرسال رسالة واحدة؛ يعيد معرّف الرسالة لحالة التسليم والتقرير. |
| POST /api/v1/send-bulk | إرسال النص نفسه لمستلمين كثيرين في طلب واحد. |
| POST /api/v1/get-balance | الرصيد المتبقي. |
| GET /api/v1/sendernames | أسماء المرسل على حسابك وحالة اعتمادها. |
| POST /api/v1/message-status/{id} | الحالة الحالية لرسالة مقبولة. |
| POST /api/v1/message-report/{id} | تقرير التسليم المفصّل لكل وجهة. |
| POST /wa/api/v1/messages | إرسال رسالة واتساب نصية. |
| GET /wa/api/v1/contacts · /conversations | جهات اتصال واتساب ومحادثاتها (مقسّمة صفحات). |
| GET/PUT/DELETE /gateway/v1/templates/{name} | حفظ قوالب بحقول دمج {{field}} أو {{field|default}} وقراءتها وحذفها. |
| POST /gateway/v1/send-template | إرسال مخصص لكل مستلم من قالب محفوظ أو نص مباشر؛ متغيرات المستلم تغلب المشتركة. |
| GET /gateway/v1/usage | حدّ الطلبات المتبقي وآخر رصيد معروف. |
| GET /gateway/v1/messages | أرشيف الرسائل المرسلة 90 يومًا: الوجهة والمرسل والطول ومعرّف الرسالة وحالة التسليم، بلا نص الرسالة. تصفية بالتاريخ والوجهة والمرسل. |
الحدود والحمايات
- حدّ 1000 طلب كل 60 ثانية لكل مفتاح على نقاط الرسائل والبوابة معًا، مع ترويستي X-RateLimit-Limit وX-RateLimit-Remaining؛ عند التجاوز 429 RATE_LIMIT مع Retry-After بالثواني المتبقية فعلًا.
- منع التكرار: الرسالة المطابقة (نفس الحساب والمستلم والنص) تُقبل مرة واحدة خلال 3600 ثانية، والتكرار 409 DUPLICATE مع X-Dedup-Window. لإعادة متعمّدة (مثل إعادة رمز تحقق) أضف X-Allow-Duplicate: true.
- إعادة آمنة: Idempotency-Key حتى 255 حرفًا على طلبات POST؛ إعادة الطلب بالمفتاح نفسه تعيد الرد الأصلي مع Idempotent-Replayed: true، والمفتاح نفسه بجسم مختلف 422 IDEMPOTENCY_KEY_REUSED.
- حماية الرصيد: عند نفاد الرصيد 402 INSUFFICIENT_BALANCE ولا تُرسل رسالة.
- كل رد يحمل X-Gateway-Request-Id؛ اذكره للدعم عند أي استفسار.
- أسماء المرسل غير المعتمدة تُرفض قبل الإرسال (403)، والنواة الخلفية معزولة عن الإنترنت وتُخدم عبر شبكة خاصة.
رموز الأخطاء
| الرمز | HTTP | المعنى |
|---|---|---|
| VALIDATION | 400 / 422 | طلب غير صالح: رقم خاطئ أو نص فارغ أو طويل أو حقل ناقص؛ message يشرح ما يُصلَّح. |
| AUTH | 401 | بيانات الاعتماد ناقصة على نقطة بوابة. |
| INSUFFICIENT_BALANCE | 402 | الرصيد منتهٍ؛ اشحن وأعد. |
| SENDER_NOT_ALLOWED · CLIENT_DISABLED | 403 | اسم مرسل غير معتمد، أو الحساب معطّل على البوابة. |
| NOT_FOUND | 404 | القالب أو النقطة غير موجود. |
| DUPLICATE · IDEMPOTENCY_IN_PROGRESS | 409 | رسالة مكررة داخل نافذة الحماية، أو طلب بالمفتاح نفسه ما زال قيد التنفيذ. |
| IDEMPOTENCY_KEY_REUSED | 422 | المفتاح استُعمل بجسم مختلف. |
| RATE_LIMIT | 429 | طلبات كثيرة؛ انتظر Retry-After. |
| INTERNAL · BAD_GATEWAY · BACKEND_UNAVAILABLE | 500 · 502 · 503 | خطأ أو انقطاع مؤقت؛ أعد المحاولة، ومع 503 انتظر Retry-After. |
| SEND_FAILED | — | كل مجموعات مستلمي إرسال القالب رُفضت؛ التفاصيل في data. |
أسئلة شائعة
كيف أنقل ربطي من مزوّد آخر؟+
غيّر النطاق إلى api.corbit.sa وضع مفتاح كوربت مكان المفتاح القديم. الصيغة تُكتشف تلقائيًا من الطلب ويُعاد الرد بالصيغة نفسها.
هل يُحفظ نص رسائلي؟+
لا. سجل الطلبات والأرشيف يحفظان الوجهة والمرسل والطول والمعرّف وحالة التسليم فقط، ولا يُحفظ المفتاح ولا نص الرسالة.
كم جزءًا تستهلك رسالتي؟+
العربي 70 حرفًا للرسالة الواحدة و67 لكل جزء إن زادت، والإنجليزي 160 ثم 153.
أين أجد التوثيق الكامل والأمثلة؟+
على api.corbit.sa/doc بالعربية والإنجليزية، مع مجموعة Postman، وأمثلة لكل نقطة بـ 25 لغة. التوثيق يُولَّد من الكود نفسه فلا يختلف عن سلوك البوابة.
تحتاج مساعدة في الربط؟
اتصال صوتي مجاني من المتصفح يصل موظفًا في المبيعات أو الدعم الفني مباشرة.