المصادقة

تُصادِق Sendveo API كل طلب بمفتاح API. تُنشأ المفاتيح وتُلغى في لوحة التحكم ضمن مفاتيح الـ API.

مفاتيح الـ API

يُعرض المفتاح كاملًا مرة واحدة فقط، عند إنشائه. احفظه بأمان. لا تحتفظ Sendveo إلا ببادئة منه لتتمكّن من التعرّف عليه لاحقًا. تعامل مع المفاتيح كما تتعامل مع كلمات المرور: لا تُودعها أبدًا في نظام التحكم بالمصدر ولا تكشفها في المتصفّح.

إرسال المفتاح

مرّر المفتاح في ترويسة X-API-KEY:

cURL

curl https://api.sendveo.com/v1/numbers \
  -H "X-API-KEY: sv_live_your_key_here"

يُقبل أيضًا رمز bearer، إذا كان أنسب لعميل HTTP لديك:

ترويسة Authorization

curl https://api.sendveo.com/v1/numbers \
  -H "Authorization: Bearer sv_live_your_key_here"

النطاقات

يحمل كل مفتاح مجموعة من النطاقات تحدّ مما يمكنه فعله. امنح ما يحتاجه التكامل المعني فقط.

النطاق	يمنح
numbers:read	عرض الأرقام وقراءتها.
numbers:write	إنشاء الأرقام والتحقّق منها وإعادة ربطها وفصلها.
messages:read	قراءة الرسائل المخزّنة.
messages:send	إرسال الرسائل.
messages:manage	التفاعل وإعادة التوجيه والحذف لدى الجميع ووسم المحادثة كمقروءة.
chats:read	سرد المحادثات وقراءتها.
chats:manage	الأرشفة والكتم وجلب السجلّ الأقدم.
contacts:read	ملفات جهات الاتصال وصورها، والتحقق من الوجود على واتساب.
groups:read	سرد المجموعات وقراءتها، وصور المجموعات.
groups:manage	إنشاء مجموعة وإضافة الأعضاء وإزالتهم والمغادرة.
webhooks:manage	قراءة webhook إعادة التوجيه وضبطه.
*:read	كل نطاقات القراءة دفعة واحدة (مفتاح للقراءة فقط).

القراءة والكتابة مفصولتان في كل مجال، وcontacts:read بلا توأم للكتابة عن قصد: فـ Sendveo لا تكتب جهة اتصال في أي مكان أبدًا. والمفتاح الصادر قبل وجود نطاق ما لا يحمله ويردّ بـ 403 على المسارات التي تحتاجه؛ ولا يمكن إضافة النطاق إليه، فأصدر مفتاحًا جديدًا.

غير مصرّح

يُرجِع المفتاح المفقود أو المُلغى أو الخارج عن النطاق الرمز 401 أو 403 مع مغلّف الخطأ القياسي:

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "The request was not authenticated."
  }
}

حساب قيد الإيقاف

أحد أنواع الرفض ليس مشكلة في المفتاح إطلاقًا: رمز 402 مع الرمز ACCOUNT_SUSPENDED يصف حالة الحساب. فالمفتاح صالح ونطاقاته سليمة، وتدويره أو إعادة تشغيل مسار الموافقة لا يغيّر شيئًا. ما دام الحساب قيد الإيقاف المؤقت، تردّ كل المسارات بالطريقة نفسها عدا تسجيل الدخول والفوترة. تواصل معنا لاستعادة الوصول.

402 Payment Required

{
  "error": {
    "code": "ACCOUNT_SUSPENDED",
    "message": "Your account is on hold. Contact us to restore access."
  }
}