الواجهة البرمجية للمطورين

أرسل رسائل واتساب للأعمال الرسمية من أي تطبيق: لارافيل أو Node.js أو بايثون أو فلاتر أو تطبيقات الجوال أو نظامك الخاص.

API v1

1الرابط الأساسي والمصادقة

كل الطلبات عبر HTTPS، ويُرسل مفتاح API كرمز Bearer في ترويسة Authorization. تجد المفتاح في لوحة التحكم ضمن ربط الموقع.

POSThttps://app.tskin.sa/api/v1/send-message.php
HTTP
POST /api/v1/send-message.php HTTP/1.1
Host: app.tskin.sa
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

2إرسال رسالة قالب

أرسل قالباً معتمداً من Meta مثل تحديث طلب أو رمز تحقق أو تذكير بموعد. القوالب تُرسل في أي وقت حتى لو لم يراسلك العميل.

الحقلالنوعالوصف
phonestringمطلوب الرقم مع رمز الدولة، أرقام فقط، مثل 966500000000.
message_typestringمطلوب "template" للقوالب.
template_namestringمطلوب اسم القالب المعتمد.
languagestringاختياري رمز لغة القالب مثل "ar" أو "en_US". الافتراضي لغة حسابك.
paramsarrayاختياري قيم متغيرات النص {{1}} و{{2}}… بالترتيب.
الطلب
{
  "phone": "966500000000",
  "message_type": "template",
  "template_name": "order_update_notice",
  "language": "ar",
  "params": ["10024", "Leather Handbag", "250 SAR"]
}
الاستجابة 200
{
  "status": "success",
  "message_id": "wamid.HBgLOTY2...",
  "recipient": "966500000000",
  "type": "template"
}

3إرسال رسالة نصية

أرسل نصاً حراً إذا راسلك العميل خلال آخر 24 ساعة. خارج هذه المدة يقبل واتساب القوالب فقط.

الحقلالنوعالوصف
phonestringمطلوبالرقم مع رمز الدولة.
message_typestringاختياري"text" (الافتراضي).
messagestringمطلوبنص الرسالة.
الطلب
{
  "phone": "966500000000",
  "message_type": "text",
  "message": "Hello! How can we help with your order today?"
}

4أمثلة برمجية

نفس طلب القالب بأربع لغات برمجة.

Terminal
curl -X POST "https://app.tskin.sa/api/v1/send-message.php" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"966500000000","message_type":"template","template_name":"order_update_notice","language":"ar","params":["10024","Leather Handbag","250 SAR"]}'

5توقيع الطلبات (اختياري)

لحماية إضافية وقّع كل طلب بمفتاح API. إذا أرسلت الترويستين نرفض أي طلب توقيعه غير مطابق أو مضى على وقته أكثر من 10 دقائق.

التوقيع هو HMAC-SHA256(body + timestamp, api_key) بصيغة hex.

PHP
$body      = json_encode($payload, JSON_UNESCAPED_UNICODE);
$timestamp = (string) time();
$signature = hash_hmac('sha256', $body . $timestamp, $apiKey);

// send these two headers with the request (use the same $body)
// X-Tskin-Timestamp: $timestamp
// X-Tskin-Signature: $signature

6رموز الاستجابة

الأخطاء تعود بالشكل {"status": "error", "message": "…"} مع أحد هذه الرموز:

الرمزالمعنىالحل
200OKتم قبول الرسالة وإرسالها إلى واتساب.
400Bad Requestتأكد من صحة JSON وصيغة الرقم والحقول المطلوبة.
401Unauthorizedمفتاح API مفقود أو غير صحيح، أو واتساب غير مربوط بالحساب.
403Forbiddenالحساب غير نشط أو الاشتراك منتهٍ أو التوقيع غير صحيح.
500Server Errorرجع واتساب بخطأ (انظر details) أو حدث خطأ لدينا. حاول مرة أخرى.

تحتاج مساعدة في الربط؟ support@tskin.sa

راسلنا