احراز هویت API

API عمومی v1 با API Key در Header احراز هویت می‌شود:

X-API-Key: YOUR_API_KEY

قواعد امنیتی

API Key را فقط سمت Server/Backend نگهداری کنید.
کلید را داخل Query String قرار ندهید.
کلید را در Repository، فایل نمونه، Analytics یا Log ثبت نکنید.
API عمومی برای فراخوانی مستقیم از JavaScript مرورگر طراحی نشده و CORS عمومی ندارد.
برای محیط‌های مختلف از Credential مستقل استفاده کنید.
در صورت افشای احتمالی، کلید باید فوراً Rotate/Revoke شود.

Credential نامعتبر یا غیرفعال با 401 Unauthorized پاسخ داده می‌شود. اگر Credential معتبر باشد اما حساب برای عملیاتی مجوز نداشته باشد، 403 Forbidden استفاده می‌شود.

Idempotency در ارسال پیام

در POST /v1/messages هدر Idempotency-Key الزامی است:

Idempotency-Key: 5c88a3d2-65ce-4cc1-9ea0-1d7efe675d40

حداکثر طول کلید ۱۰۰ نویسه است. برای هر عملیات ارسال جدید یک مقدار یکتا بسازید.

اگر Client پس از ارسال درخواست به دلیل Timeout یا قطع شبکه از نتیجه مطمئن نیست، همان Payload را با همان Idempotency-Key Retry کند. سرویس در صورت ثبت قبلی پیام، همان نتیجه را با duplicate: true برمی‌گرداند و پیام دوم ایجاد نمی‌کند.

برای یک عملیات جدید، Idempotency-Key جدید تولید کنید.

Correlation ID

برای رهگیری فنی می‌توانید Header اختیاری زیر را ارسال کنید:

X-Correlation-Id: order-140501-attempt-1

مقدار باید حداکثر ۶۴ نویسه و شامل حروف، اعداد و -، _ یا . باشد. اگر ارسال نشود یا نامعتبر باشد، SMSDaily یک شناسه جدید تولید می‌کند. این Header جایگزین Idempotency-Key نیست و از ایجاد درخواست تکراری جلوگیری نمی‌کند.