From cb29a2afbd0e9699bc59b7309c87337cda5ae0bf Mon Sep 17 00:00:00 2001
From: Seyed Morteza Mahdavi <m.mahdavy24@gmail.com>
Date: Wed, 9 Sep 2026 16:45:17 +0000
Subject: [PATCH] Add readme.md

---
 readme.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..ac4d822
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,61 @@
+
+# مستندات 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
+}
+```
\ No newline at end of file