61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
|
||
# مستندات API ارسال پیامک (Wizbox)
|
||
|
||
این سند شامل جزئیات مربوط به نحوه تعامل با سرویس ارسال پیامک از طریق API ویزباکس است.
|
||
|
||
## ۱. آدرس سرویس (Endpoint)
|
||
|
||
- **متد:** `POST`
|
||
- **آدرس:** `wizbox.ir/api/sms-order`
|
||
|
||
## ۲. احراز هویت (Authentication)
|
||
|
||
برای دسترسی به سرویس، باید توکن احراز هویت را از طریق یکی از دو روش زیر ارسال کنید:
|
||
|
||
### روش اول: هدر درخواست (پیشنهادی)
|
||
توکن ثابت را در هدر درخواست قرار دهید:
|
||
`Authorization: Bearer jJSVw8bSjuh5hQ8NW05UxGdWbR7Tjzp6el80jw5c5R85uNTlPtm6gTZEWY2t5jpM`
|
||
|
||
### روش دوم: بدنه درخواست (Body)
|
||
ارسال توکن از طریق پارامتر `token` در بدنه (Body) درخواست.
|
||
|
||
---
|
||
|
||
## ۳. پارامترهای ورودی
|
||
|
||
| پارامتر | نوع | الزامی | توضیح |
|
||
| :--- | :--- | :---: | :--- |
|
||
| `mobile` | رشته (String) | ✅ | شماره موبایل حساب ویزباکس (۱۱ رقم) |
|
||
| `customer_name` | رشته (String) | ✅ | نام صاحب حساب |
|
||
| `send_date` | رشته (String) | ✅ | تاریخ ارسال (به فرمت شمسی) |
|
||
| `send_mobile_numbers` | رشته (String) | ✅ | شمارههای گیرنده که با ویرگول از هم جدا شدهاند (مثال: `0912...,0913...`) |
|
||
| `text` | رشته (String) | ✅ | متن پیامک (**باید** شامل عبارت «لغو11» باشد) |
|
||
| `description` | رشته (String) | ❌ | توضیحات اضافی برای سفارش |
|
||
|
||
---
|
||
|
||
## ۴. کدهای وضعیت و خطاهای احتمالی
|
||
|
||
| کد وضعیت (HTTP Code) | معنی خطا / وضعیت | دلیل احتمالی |
|
||
| :--- | :--- | :--- |
|
||
| `200` | **موفقیتآمیز** | سفارش با موفقیت ثبت شد. |
|
||
| `401` | **Unauthorized** | توکن احراز هویت نامعتبر یا منقضی شده است. |
|
||
| `404` | **Not Found** | حساب کاربری برای شماره موبایل ارسالی یافت نشد. |
|
||
| `422` | **Unprocessable Entity** | اطلاعات نامعتبر (تاریخ، فرمت موبایل و...) <br> متن پیامک فاقد عبارت «لغو11» است <br> موجودی کیف پول کافی نیست |
|
||
|
||
---
|
||
|
||
## ۵. نمونه پاسخ موفق (Success Response)
|
||
|
||
در صورت ثبت موفقیتآمیز سفارش، پاسخ به صورت JSON و با کد وضعیت `200` به شرح زیر خواهد بود:
|
||
|
||
```
|
||
{
|
||
"success": true,
|
||
"message": "سفارش پیامک با موفقیت ثبت شد.",
|
||
"order_id": 1250,
|
||
"tracking_code": "SMS-8F3KXQ",
|
||
"pages": 2,
|
||
"contact_count": 5
|
||
}
|
||
``` |