SparkTG

توثيق الانتقال إلى API v2

الانتقال إلى API v2

v2

الانتقال إلى API v2

مصادقة قائمة على الرموز لتكاملك الحالي

يستدعي تكاملك واجهة SparkTG API على ‎/api/v1 مع إرسال اسم مستخدم وكلمة مرور SparkTG في كل طلب. تنتقل مصادقة الـ API إلى رموز API موقّعة، متاحة لنقاط النهاية نفسها على ‎/api/v2. تبقى نقاط النهاية والمعاملات والاستجابات كما هي: في معظم التكاملات يتغيّر فقط عنوان URL الأساسي وترويسة Authorization.

لماذا الانتقال إلى v2

ما الذي يُرسَل
اسم المستخدم + كلمة المرور (v1):كلمة مرور تسجيل الدخول، في كل طلب
رمز API (v2):رمز موقّع؛ لا تخرج أي كلمة مرور من يد مسؤولك
إذا تسرّب
اسم المستخدم + كلمة المرور (v1):يظل صالحًا حتى تُغيَّر كلمة المرور، وقد تفتح كلمة المرور نفسها لوحة التحكم أيضًا
رمز API (v2):ألغِ ذلك الرمز وحده فورًا من شاشة API Access Tokens؛ لا تتأثر تسجيلات الدخول إلى لوحة التحكم
النطاق
اسم المستخدم + كلمة المرور (v1):كل ما يمكن لذلك المستخدم الوصول إليه
رمز API (v2):خدمة واحدة فقط، محددة في الرمز
مدة الصلاحية
اسم المستخدم + كلمة المرور (v1):بلا انتهاء
رمز API (v2):تنتهي بعد عام؛ جدّدها بإنشاء رمز جديد
من يمكنه إنشاؤه
اسم المستخدم + كلمة المرور (v1):أي شخص يعرف كلمة المرور
رمز API (v2):مسؤول الخدمة فقط، بعد التحقق بكلمة مرور لمرة واحدة (OTP)
الثبات
اسم المستخدم + كلمة المرور (v1):يتعطّل عندما يغيّر أحدهم كلمة المرور
رمز API (v2):غير مرتبط بأي كلمة مرور لتسجيل الدخول
الرؤية
اسم المستخدم + كلمة المرور (v1):—
رمز API (v2):يُسجَّل كل طلب باسم خدمة الرمز

إنشاء رمز API

  1. 1افتح Admin → Settings → API Access Tokens في لوحة تحكم SparkTG.
  2. 2ضمن Generate a new token، اختر أين تستلم كلمة المرور لمرة واحدة (SMS أو WhatsApp أو Email) واطلبها.
  3. 3أدخل رمز OTP، وأضف تسمية إن شئت (مثل اسم تكاملك) ثم أنشئ الرمز.
  4. 4انسخ الرمز واحفظه بأمان. يُعرض مرة واحدة فقط، ويبقى صالحًا لمدة عام.

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

ما الذي يتغيّر

عنوان URL الأساسي
v1 (الحالي):https://telephonycloud.co.in/api/v1
v2:https://telephonycloud.co.in/api/v2
المصادقة
v1 (الحالي):Authorization: Basic <username:password>
v2:Authorization: Bearer <YOUR_TOKEN>
معرّف الخدمة (svc-id / service-id)
v1 (الحالي):يحدد الخدمة.
v2:اختياري. تأتي الخدمة دائمًا من الرمز. إن أرسلته فيجب أن يطابق خدمة الرمز، وإلا HTTP 403.
الوكيل المنفّذ للإجراء
v1 (الحالي):يُؤخذ من المعاملات التي ترسلها.
v2:كما هو. إذا لم ترسل agent-sip أو agent-id أو agent-number، يُنفَّذ الإجراء باسم المسؤول الذي أنشأ الرمز، لذا أرسل agent-sip أو agent-id أو agent-number الخاص بالوكيل.
إزالة المكالمات المجدولة
v1 (الحالي):GET أو POST
v2:DELETE فقط، والمعاملات في سلسلة الاستعلام
إرسال رسالة WhatsApp
v1 (الحالي):تُرسَل باسم وكيل المستخدم
v2:يحدد معامل الاستعلام الاختياري agent-id الوكيل المرسِل
عرض الخدمات
v1 (الحالي):جميع خدمات المستخدم
v2:خدمة الرمز فقط

الاستجابات الناجحة والأخطاء الخاصة بكل نقطة نهاية هي نفسها كما في v1. يُسجَّل كل طلب v2 لفوترة استخدام الـ API.

أمثلة

اسم المستخدم + كلمة المرور (v1)
curl -u '<username>:<password>' \
  'https://telephonycloud.co.in/api/v1/calls?service-id=<SERVICE_ID>&number=9XXXXXXXXX&agent-id=<AGENT_ID>'
رمز API (v2)
curl -H 'Authorization: Bearer <YOUR_TOKEN>' \
  'https://telephonycloud.co.in/api/v2/calls?number=9XXXXXXXXX&agent-id=<AGENT_ID>'

استبدل <YOUR_TOKEN> برمز API الخاص بك

أخطاء الرمز

يُفحص الرمز قبل تنفيذ نقطة النهاية، لذا قد يُرجع أي طلب v2 هذه الأخطاء.

HTTP 401ترويسة Authorization مفقودة أو غير صحيحة، أو انتهت صلاحية الرمز.
{"status":"error","code":401,"message":"invalid or missing JWT"}
HTTP 401أُلغي الرمز من شاشة API Access Tokens.
{"status":"error","code":401,"message":"token revoked or unknown"}
HTTP 403الخدمة التي ينتمي إليها الرمز غير نشطة.
{"status":"error","code":403,"message":"service inactive (svcId=<id>)"}
HTTP 403أُرسل المعامل svc-id أو service-id بمعرّف خدمة مختلف.
{"status":"error","code":403,"message":"svc-id does not match token's service"}

نقاط نهاية v2

هذه الواجهات متاحة على v2 اليوم. وستنتقل بقية واجهات SparkTG إلى v2 قريبًا.

إجراء مكالمة (v2)

بدء مكالمة صادرة أو مجدولة

النقر للاتصال (v2)

طلبات معاودة اتصال موثّقة برمز OTP

إزالة المكالمات المجدولة (v2)

إلغاء المكالمات المجدولة

إنشاء مكالمات مجدولة دفعةً واحدة (v2)

جدولة ما يصل إلى 500 مكالمة في طلب واحد

إرسال رسالة WhatsApp (v2)

إرسال رسالة من خدمتك

جلب تفاصيل المكالمات بالجملة (v2)

سجلات المكالمات لفترة زمنية

تقرير تسجيل الدخول / الخروج (v2)

أوقات تسجيل دخول الوكلاء وخروجهم

عرض الوكلاء (v2)

جميع وكلاء خدمة الرمز

تحديث وكيل (v2)

تسجيل الدخول والخروج والاستراحات وتعديلات الملف الشخصي

الحصول على فترات الاستراحة الفعّالة (v2)

حالات الاستراحة المتاحة للوكلاء، ولوكيل واحد اختياريًا

تقرير سجلات المكالمات CDR (الإصدار 2)

سجلات تفاصيل المكالمات لفترة زمنية محددة

تقرير أداء الوكلاء (الإصدار 2)

أعداد المكالمات وأوقات التحدث والمعالجة والانتظار والرد لكل وكيل

التقرير الخام لتسجيل الدخول والخروج (الإصدار 2)

الجدول الزمني لتسجيل الدخول والاستراحة، بصف واحد لكل مقطع حالة

تقرير ملخص تسجيل الدخول والخروج (الإصدار 2)

مدد الخمول والتحدث والاستراحة والخروج لكل وكيل

عرض الخدمات (v2)

خدمة الرمز

قائمة أرقام DID لـ LeadSquared (v2)

أرقام DID لتكامل LeadSquared