چک‌لیست اتصال Production

قبل از فعال‌کردن ارسال واقعی در محیط Production، موارد این صفحه را بررسی کنید. هدف این چک‌لیست کاهش ارسال تکراری، افشای کلید، Retry نامناسب و خطاهای دشوار برای رهگیری است.

نگهداری API Key

• X-API-Key فقط در Backend، Secret Store یا متغیر محیطی سرور نگهداری شود.
• API Key را داخل JavaScript مرورگر، Mobile App، Repository، فایل Log یا پیام خطا قرار ندهید.
• برای محیط‌های Test و Production در صورت ارائه کلیدهای مستقل، Credentialها را جدا نگه دارید.
• در صورت احتمال افشا، کلید را تعویض کنید و کلید قدیمی را از چرخه خارج کنید.

Idempotency برای ارسال

تمام عملیات ایجاد پیام که Idempotency-Key می‌پذیرند باید یک کلید پایدار برای همان عملیات داشته باشند.

order:140501:notification:payment-received

یا یک UUID که همراه رکورد عملیات در دیتابیس شما ذخیره می‌شود:

5c88a3d2-65ce-4cc1-9ea0-1d7efe675d40

اگر Request Timeout شد و معلوم نیست SMSDaily آن را دریافت کرده یا نه، همان درخواست را با همان Idempotency-Key تکرار کنید؛ برای Retry یک کلید جدید نسازید.

Timeout و Retry

پیشنهاد عملی برای Backend مشتری:

• Timeout شبکه را محدود و مشخص تنظیم کنید؛ Request نباید بدون سقف زمانی منتظر بماند.
• روی 400، 401 و خطاهای Validation بدون اصلاح درخواست Retry نکنید.
• روی 429 و خطاهای موقت 5xx از Exponential Backoff استفاده کنید.
• روی ارسال پیام، Retry فقط با همان Idempotency-Key انجام شود.
• تعداد Retry را محدود کنید و نتیجه نهایی را در Log عملیاتی ثبت کنید.

نمونه Backoff مفهومی:

1s → 2s → 4s → 8s

تفاوت پذیرش و تحویل

202 Accepted فقط به معنی پذیرفته‌شدن درخواست برای پردازش است. موفقیت نهایی را از روی trackingCode پیگیری کنید.

وضعیت‌های عمومی قرارداد:

queued
processing
sent
delivered
failed
cancelled

برنامه مشتری نباید به Status یا کد اختصاصی Provider وابسته شود.

Correlation ID و Log

SMSDaily در پاسخ‌ها X-Correlation-Id ارائه می‌کند. برای هر خطای مهم این موارد را در Log خود نگهداری کنید:

• trackingCode
• clientReference
• X-Correlation-Id
• HTTP Status Code
• زمان درخواست به UTC
• Endpoint فراخوانی‌شده

API Key، OTP و اطلاعات محرمانه را در Log ثبت نکنید.

زمان و UTC

زمان‌های قرارداد به‌صورت ISO 8601 ارسال می‌شوند. برای sendAt و زمان‌های ذخیره‌شده در Backend بهتر است UTC مبنا باشد:

2026-08-10T06:00:00Z

تبدیل به ساعت محلی را در لایه نمایش انجام دهید.

Rate Limit

در صورت دریافت 429 Too Many Requests:

1. ارسال فوری درخواست‌های جدید را کاهش دهید.
2. از Backoff استفاده کنید.
3. Retry موازی و بدون محدودیت ایجاد نکنید.
4. برای Batchهای بزرگ از Endpoint مناسب به‌جای تعداد زیادی درخواست همزمان استفاده کنید.

جزئیات بیشتر در محدودیت نرخ آمده است.

کنترل ورودی قبل از ارسال

قبل از فراخوانی API بهتر است Backend شما حداقل موارد زیر را بررسی کند:

• sender از فهرست GET /v1/senders باشد.
• شماره گیرنده خالی نباشد و در قالب مورد انتظار برنامه شما قرار گیرد.
• متن پیام خالی نباشد.
• clientReference در صورت استفاده قابل رهگیری و یکتا در Domain شما باشد.
• Pattern یا گروه خدماتی مورد استفاده برای حساب فعال باشد.

راه‌اندازی پیشنهادی

ترتیب مناسب برای Go-Live:

1. دریافت و نگهداری امن API Key.
2. فراخوانی GET /v1/senders و بررسی فرستنده فعال.
3. یک ارسال آزمایشی کنترل‌شده.
4. ذخیره trackingCode و بررسی وضعیت تا نتیجه نهایی.
5. تست Idempotency با ارسال مجدد همان درخواست و همان کلید.
6. تست مدیریت 400، 401، 429 و خطای موقت شبکه.
7. سپس فعال‌کردن ترافیک واقعی.

برای پیاده‌سازی سریع به نمونه کد چندزبانه و برای فهرست کامل مسیرها به فهرست Endpointها مراجعه کنید.