فرستنده‌ها و پیام‌های ورودی

این بخش Endpointهایی را پوشش می‌دهد که برای شناخت امکانات فعال حساب، مرور ارسال‌های قبلی و دریافت پیامک‌های ورودی استفاده می‌شوند.

فرستنده‌های مجاز حساب

GET /v1/senders
X-API-Key: YOUR_API_KEY

پاسخ فقط فرستنده‌هایی را نشان می‌دهد که برای همان حساب قابل استفاده‌اند:

[
  {
    "sender": "300099000121",
    "active": true
  },
  {
    "sender": "02112345678",
    "active": true
  }
]

مشتری باید مقدار sender را از میان فرستنده‌های مجاز حساب انتخاب کند. انتخاب مسیر داخلی سرویس‌دهنده توسط SMSDaily انجام می‌شود و بخشی از قرارداد عمومی نیست.

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

GET /v1/messages?page=1&pageSize=25
X-API-Key: YOUR_API_KEY

پارامترهای صفحه‌بندی:

نمونه پاسخ:

{
  "items": [
    {
      "trackingCode": "SMS-20260812-A1B2C3D4",
      "clientReference": "order-140501",
      "sender": "300099000121",
      "recipient": "09121234567",
      "status": "delivered",
      "partCount": 1,
      "submittedAt": "2026-08-12T05:30:00Z",
      "updatedAt": "2026-08-12T05:30:18Z"
    }
  ],
  "page": 1,
  "pageSize": 25,
  "total": 1
}

برای جزئیات کامل، متن پیام، زمان ارسال/تحویل و تاریخچه وضعیت از GET /v1/messages/{trackingCode} استفاده کنید.

پیام‌های ورودی

اگر قابلیت دریافت پیام برای حساب و شماره مربوطه فعال باشد، پیامک‌های ورودی از مسیر زیر قابل دریافت هستند:

GET /v1/inbound-messages?page=1&pageSize=25
X-API-Key: YOUR_API_KEY

نمونه پاسخ:

{
  "items": [
    {
      "trackingCode": "IN-20260812-01A2B3C4",
      "sender": "09121234567",
      "receiver": "300099000121",
      "message": "تایید",
      "receivedAt": "2026-08-12T06:25:11Z"
    }
  ],
  "page": 1,
  "pageSize": 25,
  "total": 1
}

وجود Endpoint عمومی به این معنی نیست که همه سرشماره‌ها الزاماً دریافت پیام را پشتیبانی می‌کنند. دریافت واقعی به قابلیت Provider، خط و فعال‌سازی حساب وابسته است. همچنین پیام خام Provider تنها زمانی در قرارداد عمومی ظاهر می‌شود که هسته SMSDaily آن را Parse، نرمال و به حساب درست نگاشت کرده باشد.

Polling یا Webhook؟

دو مدل همزمان قابل استفاده‌اند:

• Polling: برای سامانه‌های ساده یا بازیابی دوره‌ای، GET /v1/inbound-messages را با فاصله منطقی فراخوانی کنید.
• Webhook: برای دریافت رویداد نزدیک به زمان واقعی، روی رویداد inbound.received عضو شوید.

در هر دو روش trackingCode پیام ورودی را به‌عنوان شناسه یکتا نگهداری کنید تا پردازش تکراری انجام نشود.

برای Polling:

1. محدودیت نرخ را رعایت کنید.
2. trackingCode یا ترکیب receivedAt و شناسه محلی خود را برای جلوگیری از پردازش دوباره نگهداری کنید.
3. در خطاهای موقت 429 یا 5xx از Backoff استفاده کنید.
4. X-Correlation-Id پاسخ را در Log فنی نگهداری کنید تا پیگیری خطا ساده باشد.

برای دریافت رویدادمحور و اعتبارسنجی امضای Callback به Webhook و Callback مراجعه کنید. برای وضعیت ارسال‌ها نیز رهگیری و وضعیت تحویل را ببینید.