ابنِ على خدمات ClickLink

ماذا يمكنك أن تبني؟

واجهة الرسائل العامة تغطي الإرسال، الرصيد، حالة الرسالة، Webhooks للـDLR، وSandbox بدون إرسال حقيقي.

Authentication

استخدم واحدًا من هذه الهيدرز في كل طلب. لا تضع المفتاح في الواجهة الأمامية العامة.

X-ClickLink-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
X-Api-Key: YOUR_API_KEY

Base path: /api/v1
Host example: https://clicklink.com.sa

Send SMS

POST /api/v1/sms/send → HTTP 202

curl -sS -X POST "https://clicklink.com.sa/api/v1/sms/send" \
  -H "Content-Type: application/json" \
  -H "X-ClickLink-Key: YOUR_API_KEY" \
  -d '{"to":"05xxxxxxxx","senderId":"ClickLink","message":"Hello from ClickLink"}'

const res = await fetch("https://clicklink.com.sa/api/v1/sms/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-ClickLink-Key": process.env.CLICKLINK_API_KEY
  },
  body: JSON.stringify({
    to: "05xxxxxxxx",
    senderId: "ClickLink",
    message: "Hello from ClickLink"
  })
});
const data = await res.json();
console.log(data.messages[0].messageId);

$ch = curl_init("https://clicklink.com.sa/api/v1/sms/send");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-ClickLink-Key: " . getenv("CLICKLINK_API_KEY"),
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "to" => "05xxxxxxxx",
    "senderId" => "ClickLink",
    "message" => "Hello from ClickLink",
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);

import os, requests
r = requests.post(
  "https://clicklink.com.sa/api/v1/sms/send",
  headers={"X-ClickLink-Key": os.environ["CLICKLINK_API_KEY"]},
  json={"to":"05xxxxxxxx","senderId":"ClickLink","message":"Hello from ClickLink"},
)
print(r.json()["messages"][0]["messageId"])

الحقول الأساسية: to، senderId (معتمد للحساب)، message. registeredDelivery افتراضيًا true.

Message status

GET /api/v1/sms/messages/{messageId}

{
  "ok": true,
  "message": {
    "messageId": "…",
    "status": "delivered",
    "dlrStatus": "delivered"
  }
}

Balance: GET /api/v1/sms/balance

دورة التسليم

عند الفشل تُحدَّث الحالة عبر DLR. الاستعلام أو Webhook message.dlr يعيد status وisFinal.

Webhooks (DLR)

اضبط عنوان HTTPS عبر PUT /api/v1/billing/webhook. نوقّع كل نداء.

X-ClickLink-Signature: sha256=<HMAC_SHA256(secret, timestamp + "." + rawBody)>
X-ClickLink-Timestamp: <unix seconds>
X-ClickLink-Event: message.dlr

{
  "event": "message.dlr",
  "messageId": "…",
  "status": "delivered",
  "isFinal": true,
  "refunded": false,
  "destAddr": "9665xxxxxxxx"
}

Sandbox

بدون رسوم وبدون إرسال حقيقي. نفس جسم طلب الإرسال. الاستجابة status: SANDBOX_ACCEPTED وsandbox: true.

• GET /api/v1/sms/sandbox/ping
• POST /api/v1/sms/sandbox/send
• POST /api/v1/sms/sandbox/webhook-verify

Errors

{ "ok": false, "error": { "code": "DEST_INVALID", "message": "…" } }

Built with security in mind

• HTTPS
• API key / Bearer authentication
• Approved sender IDs
• HTTP send throttling (VALIDATION_ERROR)
• Webhook HMAC signature

الأمن والثقة