API تجارتخانه نسخه 1.0
همه درخواست‌ها کلید می‌خواهند: هدر Authorization: Bearer tk_… (کلید در نشانی پذیرفته نمی‌شود).
کلید را از پنل ← «API و کلیدها» بسازید. هر کلید فقط دسترسی‌های (scope) انتخاب‌شده را دارد و سقف درخواست در دقیقه و سهمیه روزانه دارد.
اطلاعات تماس تأمین‌کنندگان، پیام‌ها و داده‌های ورود هرگز از API برنمی‌گردد.
سیاست نسخه: تغییرات ناسازگار فقط در /api/v2 می‌آید و v1 دست‌کم ۱۲ ماه پس از اعلام v2 پشتیبانی می‌شود.
نشانی پایه: https://tejaratkhane.net/api/v1 ·
فایل OpenAPI
curl -H "Authorization: Bearer tk_xxxxxxxxxx_…" "https://tejaratkhane.net/api/v1/products?q=برنج&per_page=20"
دسترسی‌ها (scope)
| catalog.read | خواندن کاتالوگ عمومی: محصولات منتشرشده، دسته‌ها و تأمین‌کنندگان |
| products.read | خواندن همه محصولات سازمان خودم (هر وضعیت) |
| products.write | تغییر قیمت، واحد و حداقل سفارش محصولات خودم |
| stats.read | آمار بازدید محصولات و صفحه سازمان خودم |
| reports.read | گزارش تجمیعی رویدادهای سایت (کارکنان دارای مجوز گزارش) |
مسیرها
/api/v1/categories
scope: catalog.read
درخت دسته‌ها و زیرگروه‌ها
/api/v1/products
scope: catalog.read
فهرست محصولات منتشرشده
page(پرس‌وجو)per_page(پرس‌وجو)q(پرس‌وجو) — جستجوی فارسی در عنوان و مشخصاتcategory(پرس‌وجو) — شناسه دسته یا زیرگروهsupplier(پرس‌وجو) — slug تأمین‌کنندهsort(پرس‌وجو)updated_since(پرس‌وجو) — فقط موارد تغییرکرده از این زمان (ISO 8601)
/api/v1/products/{id}
scope: catalog.read
جزئیات یک محصول منتشرشده
id(مسیر) — شناسه ۸ نویسه‌ای محصول (همان که در نشانی صفحه است)
/api/v1/suppliers/{slug}
scope: catalog.read
مشخصات عمومی تأمین‌کننده (بدون اطلاعات تماس)
slug(مسیر)
/api/v1/me
scope: هر کلید
مشخصات کلید و صاحب آن
/api/v1/me/products
scope: products.read
محصولات سازمان خودم در هر وضعیت
page(پرس‌وجو)per_page(پرس‌وجو)q(پرس‌وجو) — جستجوی فارسی در عنوان و مشخصاتsort(پرس‌وجو)updated_since(پرس‌وجو) — فقط موارد تغییرکرده از این زمان (ISO 8601)
/api/v1/me/products/{id}
scope: products.read
جزئیات محصول خودم
id(مسیر) — شناسه ۸ نویسه‌ای محصول (همان که در نشانی صفحه است)
/api/v1/me/products/{id}
scope: products.write
تغییر قیمت، واحد یا حداقل سفارش
id(مسیر) — شناسه ۸ نویسه‌ای محصول (همان که در نشانی صفحه است)
/api/v1/me/stats
scope: stats.read
بازدید روزانه محصولات و صفحه سازمان خودم
days(پرس‌وجو)
/api/v1/reports/events
scope: reports.read
تعداد روزانه رویدادهای سایت (تجمیعی، بدون داده شخصی)
days(پرس‌وجو)
خطاها
پاسخ خطا همیشه JSON است و شناسه درخواست دارد؛ آن را برای پشتیبانی بفرستید.
{"error": {"code": "insufficient_scope", "message": "…"}, "request_id": "01J…"}
401 کلید نامعتبر یا لغوشده · 403 دسترسی ناکافی · 404 پیدا نشد · 422 داده نامعتبر · 429 سقف درخواست (هدر Retry-After)