# مستندات 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
}
```