ارسال پیامک

POST /v1/messages

این Endpoint یک پیام را برای پردازش ثبت می‌کند. X-API-Key و Idempotency-Key هر دو الزامی هستند.

درخواست (Request)

{
  "sender": "300099000121",
  "recipient": "09121234567",
  "message": "پیام آزمایشی SMSDaily",
  "clientReference": "order-140501"
}

هدرهای مهم (Headers)

X-API-Key: YOUR_API_KEY
Idempotency-Key: 5c88a3d2-65ce-4cc1-9ea0-1d7efe675d40
Content-Type: application/json

Idempotency-Key در محدوده همان API Key بررسی می‌شود. هنگام تلاش مجدد به‌دلیل خطای شبکه یا Timeout، کلید درخواست اصلی را حفظ کنید تا ارسال تکراری ایجاد نشود.

پاسخ پیام جدید

HTTP/1.1 202 Accepted
Location: /v1/messages/SMS-20260808-A1B2C3D4

{
  "trackingCode": "SMS-20260808-A1B2C3D4",
  "status": "queued",
  "encoding": "Persian",
  "characterCount": 23,
  "partCount": 1,
  "submittedAt": "2026-08-08T05:30:00Z",
  "duplicate": false
}

trackingCode شناسه اصلی پیگیری مشتری است. شناسه دیتابیس و شناسه Provider بخشی از قرارداد عمومی نیستند.

تلاش مجدد برای درخواست ثبت‌شده

اگر همان درخواست با همان Idempotency-Key دوباره دریافت شود، سرویس پیام جدیدی ایجاد نمی‌کند و پاسخ موجود را با 200 OK برمی‌گرداند:

{
  "trackingCode": "SMS-20260808-A1B2C3D4",
  "status": "queued",
  "encoding": "Persian",
  "characterCount": 23,
  "partCount": 1,
  "submittedAt": "2026-08-08T05:30:00Z",
  "duplicate": true
}

Encoding و تعداد بخش

پاسخ، encoding، characterCount و partCount محاسبه‌شده را برمی‌گرداند تا Backend مشتری بداند پیام با چه مشخصاتی ثبت شده است. جزئیات تعرفه و هزینه در قرارداد مالی حساب مدیریت می‌شود و نباید از روی تعداد نویسه به‌صورت مستقل حدس زده شود.