1الرابط الأساسي والمصادقة
كل الطلبات عبر HTTPS، ويُرسل مفتاح API كرمز Bearer في ترويسة Authorization. تجد المفتاح في لوحة التحكم ضمن ربط الموقع.
https://app.tskin.sa/api/v1/send-message.phpPOST /api/v1/send-message.php HTTP/1.1
Host: app.tskin.sa
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json2إرسال رسالة قالب
أرسل قالباً معتمداً من Meta مثل تحديث طلب أو رمز تحقق أو تذكير بموعد. القوالب تُرسل في أي وقت حتى لو لم يراسلك العميل.
| الحقل | النوع | الوصف | |
|---|---|---|---|
phone | string | مطلوب | الرقم مع رمز الدولة، أرقام فقط، مثل 966500000000. |
message_type | string | مطلوب | "template" للقوالب. |
template_name | string | مطلوب | اسم القالب المعتمد. |
language | string | اختياري | رمز لغة القالب مثل "ar" أو "en_US". الافتراضي لغة حسابك. |
params | array | اختياري | قيم متغيرات النص {{1}} و{{2}}… بالترتيب. |
{
"phone": "966500000000",
"message_type": "template",
"template_name": "order_update_notice",
"language": "ar",
"params": ["10024", "Leather Handbag", "250 SAR"]
}{
"status": "success",
"message_id": "wamid.HBgLOTY2...",
"recipient": "966500000000",
"type": "template"
}3إرسال رسالة نصية
أرسل نصاً حراً إذا راسلك العميل خلال آخر 24 ساعة. خارج هذه المدة يقبل واتساب القوالب فقط.
| الحقل | النوع | الوصف | |
|---|---|---|---|
phone | string | مطلوب | الرقم مع رمز الدولة. |
message_type | string | اختياري | "text" (الافتراضي). |
message | string | مطلوب | نص الرسالة. |
{
"phone": "966500000000",
"message_type": "text",
"message": "Hello! How can we help with your order today?"
}4أمثلة برمجية
نفس طلب القالب بأربع لغات برمجة.
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"]}'<?php
$apiKey = "YOUR_API_KEY";
$url = "https://app.tskin.sa/api/v1/send-message.php";
$payload = [
"phone" => "966500000000",
"message_type" => "template",
"template_name" => "order_update_notice",
"language" => "ar",
"params" => ["10024", "Leather Handbag", "250 SAR"],
];
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$apiKey}",
"Content-Type: application/json",
],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;const axios = require('axios');
axios.post('https://app.tskin.sa/api/v1/send-message.php', {
phone: '966500000000',
message_type: 'template',
template_name: 'order_update_notice',
language: 'ar',
params: ['10024', 'Leather Handbag', '250 SAR']
}, {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
})
.then(res => console.log(res.data))
.catch(err => console.error(err.response ? err.response.data : err.message));import requests
url = "https://app.tskin.sa/api/v1/send-message.php"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
}
payload = {
"phone": "966500000000",
"message_type": "template",
"template_name": "order_update_notice",
"language": "ar",
"params": ["10024", "Leather Handbag", "250 SAR"],
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())5توقيع الطلبات (اختياري)
لحماية إضافية وقّع كل طلب بمفتاح API. إذا أرسلت الترويستين نرفض أي طلب توقيعه غير مطابق أو مضى على وقته أكثر من 10 دقائق.
التوقيع هو HMAC-SHA256(body + timestamp, api_key) بصيغة hex.
$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: $signature6رموز الاستجابة
الأخطاء تعود بالشكل {"status": "error", "message": "…"} مع أحد هذه الرموز:
| الرمز | المعنى | الحل |
|---|---|---|
| 200 | OK | تم قبول الرسالة وإرسالها إلى واتساب. |
| 400 | Bad Request | تأكد من صحة JSON وصيغة الرقم والحقول المطلوبة. |
| 401 | Unauthorized | مفتاح API مفقود أو غير صحيح، أو واتساب غير مربوط بالحساب. |
| 403 | Forbidden | الحساب غير نشط أو الاشتراك منتهٍ أو التوقيع غير صحيح. |
| 500 | Server Error | رجع واتساب بخطأ (انظر details) أو حدث خطأ لدينا. حاول مرة أخرى. |
تحتاج مساعدة في الربط؟ support@tskin.sa
راسلنا