بخش‌های مستندات

راهنمای کامل استفاده از API

مقدمه

این مستندات راهنمای کامل استفاده از وب‌سرویس پیامکی است که امکان ارسال و دریافت پیامک، بررسی وضعیت ارسال، و مدیریت حساب کاربری را فراهم می‌کند.

نکته مهم: تمام درخواست‌ها باید شامل کلید API در هدر باشند.

ویژگی‌های اصلی:

  • ارسال پیامک با قابلیت تنظیم اولویت
  • دریافت وضعیت ارسال پیام‌ها
  • دریافت پیام‌های ورودی از طریق Webhook
  • مدیریت تراز حساب

مفاهیم

JSON: فرمتی ساده و قابل فهم برای ذخیره و انتقال پیام است. در این فرمت معمولاً از ساختار value:key استفاده می‌شود.
مثال: {کلید: مقدار}
کلید: کلیدها عناوین مقادیری هستند که باید در Header هر درخواست وب‌سرویس ارسال شوند.
Request HTTP: درخواستی که در قالب پروتکل http ارسال می‌شود. این درخواست در ساده‌ترین حالت شامل دو بخش Header و Body می‌شود.
Response HTTP: پاسخی که در پاسخ به درخواست http به کاربر داده می‌شود. این مورد یک پیام و یک کد وضعیت دارد. کد وضعیت به‌طور کلی مشکل اصلی را به شما نشان می‌دهد:
  • کد وضعیت 200: همه چیز درست است و شما پاسخ نرمال دریافت کرده‌اید
  • کد 404: اشتباه بودن آدرس URL
  • کد 401: عدم دسترسی کافی
Key API: یک کلید امنیتی است که باید در حفظ و محرمانگی آن کوشا باشید. این کلید شرط دسترسی به وب‌سرویس و ارسال پیام از طریق آن است.
Header: همان Header HTTP است که بر روی بسته‌های HTTP قرار می‌گیرد و مواردی از جمله نوع داده، کلید دسترسی و... را در آن تعیین می‌کنند.
Type-Content: یک مقدار اجباری در Header HTTP و تعیین‌کننده نوع محتوا است:
  • در وب‌فرم‌ها: data-form/multipart
  • در ارسال داده‌ها در قالب JSON: json/application
Request POST: نوعی از درخواست HTTP که تعیین‌کننده هدف درخواست است. در استفاده از وب‌سرویس‌های این مستند همواره درخواست‌های از نوع POST استفاده می‌گردد.

تعیین کلید

نیاز به کلید: برای بهره‌مندی از وب‌سرویس یک کلید داشته باشید. این کلید باید در قسمت هدر درخواست شما قرار گیرد.
نحوه ارسال کلید در هدر
curl -X POST https://api.example.com/endpoint \\
  -H "key-api-x: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "data": "your_data"
  }'
هشدار: در صورتی‌که کلید در درخواست HTTP شما شناسایی نشود یا غلط باشد، با خطای 401 مواجه خواهید شد.
تولید کلید: کلید در پنل کاربری هر کاربر قابل تولید و نمایش است.

ارسال پیامک

پارامترها: همواره مقادیری هستند که برای ارسال پیامک نیاز است. برای ارسال پیام می‌بایست از آدرس زیر استفاده نمایید:
آدرس API
https://<your-provider-domain>/api/v3.0.1/send

جدول پارامترهای ارسال پیامک:

عنوان پارامتر شرح نوع داده اجباری/اختیاری
srcNum شماره مبدا که قرار است با آن ارسال انجام شود string اجباری
recipient شماره گیرنده/مخاطب string اجباری
body بدنه پیام/پیام اصلی string اجباری
customerId شناسه پیام (CheckingId) long اختیاری
type نوع پیام int اختیاری
retryCount تعداد دفعات تکرار در صورت موفق نبودن ارسال int اختیاری
validityPeriod زمان انقضای پیام به ثانیه int اختیاری
نکته مهم: در ابتدای شماره تلفن‌ها و شماره ارسال‌کننده کد کشور (98 برای ایران)، باید قرار گیرد.

نمونه درخواست ارسال CURL:

درخواست ارسال پیامک
curl -X POST -H "Content-Type: application/json" -H "x-api-key: <YOUR_API_KEY>" -d '[{"srcNum":"value1", "recipient":"value2","body":"message","customerId":id}]' https://<your-provider-domain>/api/v3.0.1/send
نکات مهم:
  • مقادیر از نوع رشته یا string الزاماً داخل " قرار می‌گیرند. مثال: "پیام من"
  • در وارد کردن عناوین (یا به‌عبارتی همان key) باید حروف بزرگ و کوچک رعایت شود
  • فراموش نکنید که در صورت وارد نکردن کلید در هدر پیام، با وضعیت 401 مواجه خواهید شد
  • حتماً Type-Content را در Header خود به‌صورت json/application قرار دهید
  • امکان ارسال چندین پیام در یک درخواست وجود دارد، اما مؤکداً توصیه می‌شود در هر درخواست حداکثر 100 پیام وجود داشته باشد. به این منظور باید بدنه درخواست را به‌صورت آرایه‌ای از Object JSON ها ارسال کنید. به این شکل:
فرمت آرایه برای چندین پیام
[{M1},{M2},{M3}]

نمونه body ارسال تک پیام:

JSON Body - تک پیام
[
  {
    "srcNum": "982142750000",
    "recipient": "98912*******",
    "body": "تست پیام وب سرویس",
    "customerId": 1,
    "type": 5,
    "retryCount": 2,
    "validityPeriod": 10
  }
]

نمونه body ارسال چند پیام (چند به چند):

JSON Body - چندین پیام
[
  {
    "srcNum": "982142750000",
    "recipient": "98912*******",
    "body": "تست پیام وب سرویس",
    "customerId": 1,
    "type": 5,
    "retryCount": 2,
    "validityPeriod": 10
  },
  {
    "srcNum": "982142750000",
    "recipient": "98912*******",
    "body": "تست پیام وب سرویس",
    "customerId": 2,
    "type": 5,
    "retryCount": 2,
    "validityPeriod": 10
  }
]

توضیحات مربوط به تضمین کیفیت

Type: به منظور کنترل کیفیت ارسال پیام کوتاه نیاز است کاربرد آن تعیین گردد، اولویت ارسال و سرعت تخلیه ارسال‌ها به سمت اپراتور بر اساس Type ارسال تنظیم و دسته‌بندی می‌گردد، حساسیت سیستم بر روی Type های با اولویت بالاتر و Availability بالاتر بر اساس Type ها تنظیم می‌گردد.
نوع پیام: نوع پیام می‌تواند مقداری بین 0 تا 5 باشد، چنانچه مقدار صفر باشد یا مقداری اختصاص داده نشود؛ به این معنی است ارسال طبق استاندارد جاری سیستم انجام می‌شود و هیچ اولویتی در ارسال پیام لحاظ نمی‌گردد.

جدول انواع کاربرد:

نوع کاربرد توضیحات
1 رمز یکبار مصرف
2 تراکنش
3 تعهدی
4 اطلاع‌رسانی
5 تبلیغات

Retry Count:

تلاش مجدد بر روی وضعیت‌های ناموفق به صورت سیستمی صورت می‌پذیرد، تعداد تلاش می‌تواند مقداری بین 0 تا 10 باشد. عدد صفر به معنای عدم تلاش مجدد و عدد 10 به معنای 10 بار تلاش مجدد برای ارسال پیام است. تا اتمام فرایند تلاش مجدد وضعیت پیام در حالت "در انتظار تلاش مجدد" باقی می‌ماند.

Validity Period:

این امکان مشخص‌کننده زمان مورد انتظار برای ارسال پیام به اپراتور است، این پارامتر به صورت اختیاری در هر سفارش ارسال توسط ارسال‌کننده به واحد ثانیه قابل تنظیم و مقدار آن می‌تواند از 0 تا 172800 ثانیه باشد. چنانچه مقدار آن صفر یا خالی باشد، مقدار پیش‌فرض سیستم اعمال خواهد شد.

پاسخ سرور به درخواست (Response HTTP):

پاسخ به درخواست نیز در قالب JSON ارائه می‌شود. چنانچه کد 200 را دریافت کنید به این معنی است که درخواست شما بدون مشکل انجام شده است.

پاسخ در زمان اشتباه بودن Key API:

خطای 401 - کلید API نامعتبر
{
  "statusCode": 401,
  "timestamp": "2024-09-20T02:42:38.056+04:30",
  "message": "API key is not valid.",
  "description": "uri=/api/v3.0.1/send",
  "payload": null
}

نمونه پاسخ موفق:

پاسخ موفق - کد 200
[
  {
    "messageId": 628149526253312,
    "srcNum": "9821****",
    "recipient": "989****",
    "customerId": 20,
    "status": "ACCEPTED",
    "statusCode": 200
  },
  {
    "messageId": 628149526257408,
    "srcNum": "9899****",
    "recipient": "989****",
    "customerId": 20,
    "status": "ACCEPTED",
    "statusCode": 200
  }
]

توضیحات Object نتیجه ارسال:

عنوان پارامتر شرح نوع داده
messageId شناسه ارسال که هنگام پردازش پیام تولید می‌شود Int
srcNum شماره ارسال‌کننده String
recipient شماره گیرنده String
customerId شناسه پیام برای پیگیری‌های کاربر Long
status وضعیت پیام String
statusCode کد وضعیت Int
نکته مهم: چنانچه شما پاسخی با کد وضعیت 200 دریافت کردید، این مورد الزاماً به معنای ارسال پیام نیست و باید به وضعیت در پاسخ دریافتی یا همان status توجه کنید. چنانچه ارسال پیام تأیید نشود با REJECTED در این فیلد مواجه خواهید شد.
موارد خطا: در صورتی‌که وضعیت پیام (statusCode=200) به معنای ارسال موفق نباشد؛ ممکن است هرکدام از موارد زیر باشد، که در این صورت در پردازش یا ارسال پیام مشکلی وجود داشته است:
  • محتوا به دلیل حساسیت آن تأیید نشده است
  • ارسال ایموجی از این مسیر میسر نیست
  • شماره گیرنده دچار اشکال است
  • شماره ارسال دچار اشکال است
خطای 400: خطای 400 نیز در شرایطی رخ می‌دهد که درخواست در فرمت نادرستی ارسال شده یا چنانچه شما اعتبار کافی نداشته نباشید. در این حالت پاسخ message برابر با credit insufficient خواهد بود.

دریافت وضعیت

وضعیت پیام روزانه:

در این روش امکان دریافت وضعیت از پیام‌های ارسال شده در 48 ساعت گذشته فراهم است. در این حالت می‌توان برای دریافت وضعیت پیام ارسال شده از روش زیر اقدام نمود.
آدرس API وضعیت روزانه
https://<your-provider-domain>/api/v3.0.1/get-status-customer-id
از طریق این آدرس، دریافت وضعیت پیام‌ها با استفاده از customerId امکان‌پذیر است. می‌توان وضعیت پیام را بالفاصله پس از ارسال پیام دریافت کرد. به موجب اینکه شناسه مورد نظر توسط فرستنده پیام ساخته و پردازش می‌شود، این شناسه به CheckingID نیز شناخته می‌شود.

وضعیت پیام آرشیو شده:

در این روش امکان دریافت وضعیت از پیام‌هایی که از زمان ارسال آن بیش از 48 ساعت گذشته است، فراهم است. در این حالت می‌توان برای دریافت وضعیت پیام ارسال شده از روش زیر اقدام نمود.
به موجب اینکه ذخیره‌سازی ارسال در سرور آرشیو در بخش‌های جداگانه‌ای به صورت روزانه انجام می‌گردد، تاریخ ارسال می‌بایست با فرمت زیر در URL وضعیت‌گیری سرویس آرشیو وارد گردد:
آدرس API وضعیت آرشیو
https://<your-provider-domain>/api/v3.0.1/get-status-customer-id
نکته: در مثال فوق تاریخ بیست و سوم، ماه 10 سال 2023 در نظر گرفته شده است و می‌توانید تاریخ دلخواه را در آن جایگزین کنید. باید Body درخواست خود را لیستی از شناسه‌ها قرار دهید تا وضعیت آنها را مشاهده کنید.

نمونه Body درخواست:

لیست شناسه‌های وضعیت‌گیری
[
  11743884951599,
  11743884951600,
  11743884951601,
  11743884951602,
  11743884951603,
  11743884951598
]
وضعیت‌گیری موارد فوق با استفاده از شناسه customerId انجام شده؛ اما می‌توان با استفاده از همین ساختار و به‌کارگیری شناسه پیام (messageId) نیز این مورد را به انجام رساند.

دریافت وضعیت با messageId:

آدرس API وضعیت با messageId
https://<your-provider-domain>/api/v3.0.1/get-status
نکات مهم:
  • برای ارسال درخواست به آدرس فوق الزم است کلید key-api-x در هدر درخواست در نظر گرفته شود
  • چنانچه در فراخوانی این آدرس با خطای 401 مواجه شدید به معنای قرار نگرفتن کلید در هدر است

دریافت وضعیت آرشیو با messageId:

آدرس API وضعیت آرشیو با messageId
https://<your-provider-domain>/api/v3.0.1/get-status-archive/2023-10-23
نکته: در مثال فوق تاریخ بیست و سوم، ماه 10 سال 2023 در نظر گرفته شده است و می‌توانید تاریخ دلخواه را در آن جایگزین کنید. باید Body درخواست خود را لیستی از شناسه‌ها قرار دهید تا وضعیت آنها را مشاهده کنید.

جدول وضعیت‌های دریافتی:

کد وضعیت عنوان انگلیسی عنوان فارسی وضعیت نهایی بازگشت اعتبار
-1 FOUND NOT پیام یافت نشد - -
0 ENQUEUED پیام در صف ارسال قرار دارد خیر خیر
1 DELIVERED پیام به گوشی رسید بله خیر
2 PENDING در انتظار تعیین وضعیت خیر خیر
3 FAILED خطا در ارسال بله بله
4 BLACKLISTED لیست سیاه بله بله
7 REJECT رد شده بله بله

پیام های دریافتی

Hook Web: یک ساختار تعاملی کاربر با سامانه پیامکی ایجاد می‌کند و از آن برای نمایش پیام‌های ورودی به کاربر استفاده می‌شود.
اگر قصد دریافت پیام بر پایه Hook Web را دارید، می‌توانید با ثبت آدرس URL دلخواه خود از طریق پنل کاربری در بخش شماره پیام کوتاه، به ازای هر شماره ارسال‌کننده، پیام‌های دریافتی را در آدرس مورد نظر دریافت نمایید. روش دریافت تنها به‌صورت String Query بوده و مقادیر در نوار آدرس نمایش داده می‌شوند.

پارامترهای قابل دریافت:

پارامتر توضیحات
Text محتوا
Timestamp زمان ارسال
From فرستنده
To گیرنده
MessageID شناسه پیام

نمونه آدرس Hook Web:

آدرس نمونه با پارامترها
YourDomain/?text=11×tamp=2023-11-20 14:13:17&from=98912XXXXXXX&to=9821XXXXX

دریافت تراز حساب

برای دریافت تراز حساب الزامی برای ورود به پنل ندارید و با همان کلید می‌توانید اعتبار دریافت کنید.
آدرس API دریافت تراز
https://<your-provider-domain>/api/v3.0.1/balance
برای دریافت اعتبار فعلی نیاز به ارسال هیچ داده‌ای نبوده و تنها کافی است در Header خود key-api-x را قرار دهید. به این ترتیب در پاسخ تنها یک عدد دریافت خواهید کرد؛ که نشان‌دهنده اعتبار فعلی حساب شما است.

نمونه درخواست CURL:

درخواست دریافت تراز
curl -X GET https://<your-provider-domain>/api/v3.0.1/balance \\
  -H "key-api-x: YOUR_API_KEY"

نمونه پاسخ:

پاسخ تراز حساب
1000
نکته: پاسخ دریافتی یک عدد ساده است که نشان‌دهنده اعتبار فعلی حساب شما می‌باشد.