API ارسال و پیگیری پیام برای سایت و نرم‌افزار

مراحل اتصال API پیامک

1. برای سایت یک کلید جدا بسازید

   از پنل مدیر کلید مخصوص همان برنامه را بسازید. اگر چند وب‌سایت دارید، برای هرکدام کلید جدا نگه دارید تا دسترسی را مستقل لغو کنید.

2. کلید را در بک‌اند محرمانه نگه دارید

   کلید باید در متغیر محیطی یا مخزن امن سرور برنامه باشد. آن را داخل JavaScript، اپلیکیشن قابل دانلود، HTML، مخزن عمومی یا گزارش خطا قرار ندهید.

3. درخواست ثبت پیام بفرستید

   برای ثبت پیام از POST به مسیر /api/v1/messages و هدر X-API-Key استفاده کنید. بدنه شامل شمارهٔ مقصد و متن است. برای جلوگیری از ثبت تکراری در retry، Idempotency-Key یکتا و ثابت همان عملیات را بفرستید.

4. وضعیت را با شناسهٔ پاسخ بخوانید

   پاسخ 202 شناسهٔ پیام و وضعیت اولیه را برمی‌گرداند. سپس GET به /api/v1/messages/{id} وضعیت همان پیام متعلق به همان کلید را ارائه می‌کند.

POST /api/v1/messages HTTP/1.1
Host: itfa-sms.ir
Content-Type: application/json
X-API-Key: itsms_<SERVER_SIDE_SECRET>
Idempotency-Key: order-10452

{
  "to": "09XXXXXXXXX",
  "text": "پیام نمونه برای مخاطب مجاز"
}

HTTP/1.1 202 Accepted
{
  "id": "<message-id>",
  "status": "queued"
}

محدودیت‌ها و معنی وضعیت‌های API

امنیت اتصال سایت به API پیامک

API را فقط از بک‌اند سایت فراخوانی کنید. HTTPS را فعال نگه دارید، کلید را در خروجی مرورگر یا کد سمت کاربر قرار ندهید و دسترسی شبکه به پنل را محدود کنید. ارتباط مستقیم سایت با پورت مدیریتی مودم یا MikroTik لازم نیست؛ پنل مسیر دستگاه را از شبکهٔ سرور مدیریت می‌کند.

پرسش‌های متداول API