واجهة برمجية مفتوحة
واجهة محجوز البرمجية
اربط أنظمتك مع محجوز. أدِر الطلبات والعملاء والخدمات والموظفين والحجوزات برمجياً.
https://api.mahjoz.io/api/open/v1المصادقة
تستخدم الواجهة البرمجية بروتوكول OAuth2 Client Credentials. احصل على بيانات الاعتماد من لوحة تحكم محجوز.
1
احصل على بيانات الاعتماد
أنشئ عميل API من لوحة تحكم محجوز. احفظ client_id و client_secret — يُعرض المفتاح السري مرة واحدة فقط.
إعدادات الواجهة البرمجية2
احصل على رمز الوصول
POST /oauth/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "<client_id>",
"client_secret": "<client_secret>",
"scope": ""
}3
استخدم الرمز
Authorization: Bearer <access_token>حدود الطلبات
الطلبات محدودة لكل عميل. الحد الافتراضي: 60 طلب/دقيقة. عند التجاوز، يُرجع الخادم 429 Too Many Requests مع ترويسة Retry-After.
الصلاحيات
| الصلاحية | الوصف |
|---|---|
orders:read | قراءة الطلبات |
orders:write | إنشاء الطلبات والتحقق من التوفر |
customers:read | قراءة العملاء |
customers:write | إنشاء العملاء |
items:read | قراءة العناصر (الخدمات والمنتجات) |
staff:read | قراءة الموظفين وخدماتهم |
branches:read | قراءة الفروع |
categories:read | قراءة التصنيفات |
* | جميع الصلاحيات |
التصفح
تُرجع نقاط النهاية نتائج مقسّمة على صفحات. استخدم per_page (الافتراضي 25، الأقصى 100) و page.
{
"data": [...],
"links": { "first": "...", "last": "...", "prev": null, "next": "..." },
"meta": { "current_page": 1, "last_page": 5, "per_page": 25, "total": 120 }
}معالجة الأخطاء
| رمز HTTP | رمز الخطأ | الوصف |
|---|---|---|
| 401 | authentication_failed | رمز مفقود أو غير صالح أو منتهي الصلاحية |
| 403 | insufficient_scope | الرمز لا يملك الصلاحية المطلوبة |
| 403 | feature_disabled | الواجهة البرمجية غير متاحة في الباقة الحالية |
| 422 | validation_error | بيانات الطلب غير صالحة |
| 422 | timeslot_unavailable | الوقت المطلوب غير متاح |
| 429 | — | تم تجاوز حد الطلبات |
| 502 | availability_check_failed | خدمة الحجز غير قابلة للوصول |
نقاط النهاية
| الطريقة | نقطة النهاية | الصلاحية |
|---|---|---|
| GET | /orders | orders:read |
| GET | /orders/{uuid} | orders:read |
| POST | /orders | orders:write |
| POST | /availability | orders:write |
| GET | /customers | customers:read |
| GET | /customers/{uuid} | customers:read |
| GET | /customers/phone | customers:read |
| POST | /customers | customers:write |
| GET | /items | items:read |
| GET | /items/{uuid} | items:read |
| GET | /staff | staff:read |
| GET | /staff/{uuid} | staff:read |
| GET | /branches | branches:read |
| GET | /categories | categories:read |