# مستندات API ربات میرزا

این مرجع تمام اندپوینت‌های مدیریتی ربات را پوشش می‌دهد: کاربران، فاکتورها، پرداخت‌ها، محصولات، پنل‌ها، دسته‌بندی‌ها، کدهای تخفیف و تنظیمات. همهٔ درخواست‌ها با یک توکن ثابت احراز هویت می‌شوند و بدنه و پاسخ‌ها JSON هستند.

## شروع کار

آدرس پایه را در نوار بالا وارد کنید تا همهٔ نمونه‌کدهای این صفحه با دامنهٔ شما به‌روز شوند.

### مشخصات کلی

آدرس پایه
  https://example.com/api
قالب
  application/json
احراز هویت
  Token: <token>
انکودینگ
  UTF-8

### گرفتن توکن

در ربات دستور `/token2` را بفرستید. ربات یک توکن تازه می‌سازد، آن را در `api/hash.txt` ذخیره می‌کند و برایتان می‌فرستد. با هر بار اجرای این دستور توکن قبلی باطل می‌شود.

کلید `APIKEY` موجود در `config.php` هم به‌عنوان توکن معتبر پذیرفته می‌شود.

### یک درخواست نمونه

هر درخواست یک `actions` در بدنه دارد که مشخص می‌کند کدام عملیات اجرا شود.

curl

پاسخ ۲۰۰

## قواعد مشترک

این قواعد در تمام اندپوینت‌ها یکسان‌اند.

### متد و بدنه

هر اکشن متد مشخص خودش را دارد؛ اکشن‌های خواندنی `GET` و اکشن‌های تغییردهنده `POST`. اگر متد اشتباه باشد پاسخ `405` با پیام `method invalid` برمی‌گردد.

توجه: اکشن‌های `GET` هم بدنهٔ JSON می‌گیرند. بعضی کتابخانه‌ها بدنهٔ درخواست GET را حذف می‌کنند؛ در آن صورت باید کلاینت را طوری تنظیم کنید که بدنه را نگه دارد، وگرنه پاسخ `data invalid` می‌گیرید.

### ساختار پاسخ

همهٔ اندپوینت‌ها به‌جز `/keyboard`، `/log` و `/statbot` پاسخ را در یک پوشش ثابت برمی‌گردانند.

فیلد | نوع | توضیح
--- | --- | ---
status | boolean | موفقیت عملیات. در خطاهای اعتبارسنجی `false` است حتی وقتی کد HTTP ۲۰۰ باشد.
msg | string | پیام وضعیت یا شرح خطا.
obj | object | array | دادهٔ پاسخ. در عملیات‌های بدون خروجی آرایهٔ خالی است.

### صفحه‌بندی

اکشن‌های فهرستی این سه پارامتر را می‌پذیرند و یک شیء `pagination` برمی‌گردانند.

پارامتر | نوع | پیش‌فرض | توضیح
--- | --- | --- | ---
limit | number | 50 | تعداد رکورد در هر صفحه، بین ۱ تا ۱۰۰۰.
page | number | 1 | شمارهٔ صفحه از ۱ به بالا.
q | string | — | عبارت جستجو. ستون‌های جستجو در هر اکشن ذکر شده است.

### خطاها

کد | پیام | علت
--- | --- | ---
403 | token invalid | هدر `Token` ارسال نشده یا با توکن سرور یکی نیست.
405 | method invalid | متد HTTP با متد اکشن نمی‌خواند.
200 | data invalid | بدنه JSON معتبر نیست یا خالی است.
200 | Action Invalid | مقدار `actions` برای این اندپوینت شناخته‌شده نیست.
200 | Missing required fields: … | یک یا چند پارامتر الزامی ارسال نشده است.
200 | <field> invalid / out of range | پارامتر عددی نیست یا خارج از بازهٔ مجاز است.
500 | Database error occurred | خطای پایگاه داده. جزئیات در `error_log` ثبت می‌شود.

### ثبت درخواست‌ها

هر درخواست موفقِ احراز هویت‌شده با هدرها، بدنه، IP و نام اکشن در جدول `logs_api` ذخیره می‌شود.