مستندات API ربات میرزا
این مرجع تمام اندپوینتهای مدیریتی ربات را پوشش میدهد: کاربران، فاکتورها، پرداختها، محصولات، پنلها، دستهبندیها، کدهای تخفیف و تنظیمات. همهٔ درخواستها با یک توکن ثابت احراز هویت میشوند و بدنه و پاسخها JSON هستند.
شروع کار
آدرس پایه را در نوار بالا وارد کنید تا همهٔ نمونهکدهای این صفحه با دامنهٔ شما بهروز شوند.
مشخصات کلی
- آدرس پایه
- https://example.com/api
- قالب
- application/json
- احراز هویت
- Token: <token>
- انکودینگ
- UTF-8
گرفتن توکن
در ربات دستور /token2 را بفرستید. ربات یک توکن تازه میسازد، آن را در
api/hash.txt ذخیره میکند و برایتان میفرستد. با هر بار اجرای این
دستور توکن قبلی باطل میشود.
کلید APIKEY موجود در config.php هم
بهعنوان توکن معتبر پذیرفته میشود.
یک درخواست نمونه
هر درخواست یک actions در بدنه دارد که مشخص میکند کدام عملیات اجرا شود.
قواعد مشترک
این قواعد در تمام اندپوینتها یکساناند.
متد و بدنه
هر اکشن متد مشخص خودش را دارد؛ اکشنهای خواندنی 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 ذخیره میشود.