مرجع API v1
كل نقطة نهاية في واجهة REST مع طريقتها ومسارها والنطاق المطلوب، مولّدة من مستند OpenAPI نفسه الذي تقدمه الواجهة.
GET https://<workspace>.zmle.com/api/v1/me
البدء السريع
- افتح عرضًا تجريبيًا فوريًا: مساحة عمل ببيانات نموذجية
- في العرض التجريبي افتح الإدارة ← التكاملات والواجهة البرمجية وأنشئ مفتاحًا
- استدعِ GET /api/v1/me بالمفتاح (أدناه) لترى مساحة العمل والشخص المرتبطين به
- أضف نقطة نهاية لخطاف ويب واختر الأحداث؛ في العرض التجريبي تُسجَّل التسليمات ولا تُرسل
مستند OpenAPI
المواصفة الكاملة عامة، ولا تحتاج إلى مفتاح لقراءتها: https://zmle.com/api/v1/openapi.json
curl https://<your-demo>.zmle.com/api/v1/me \ -H "Authorization: Bearer $ZMLE_API_KEY"
العنوان الأساسي
تجيب كل مساحة عمل على عنوانها الخاص: https://<workspace>.zmle.com/api/v1 (أو نطاقها الخاص). مضيف الواجهة https://api.zmle.com/v1 يجد مساحة العمل من المفتاح.
المصادقة
أرسل المفتاح في Authorization: Bearer <key> (أو X-Api-Key). تستخدم التطبيقات الأصلية والمتصلة OAuth 2.1 مع PKCE ورموز تطبيق قصيرة العمر.
القوائم والتصفح
تقبل القوائم page وper (من 1 إلى 100، الافتراضي 25)، وq للبحث، وsince للتغييرات بعد تاريخ. يحمل الرد total وpages، مع ترويستي Link وX-Total-Count.
الأخطاء
الأخطاء بصيغة JSON: { error: { code, message } } مع حالة HTTP. لكل رد X-Request-Id. تقبل طلبات POST ترويسة Idempotency-Key. لكل مفتاح رصيد من 300 طلب يُعاد ملؤه بمعدل 5 في الثانية؛ تُظهر X-RateLimit-Remaining المتبقي، ويأتي الرمز 429 مع Retry-After.
الإصدارات والإيقاف التدريجي
الإصدار v1 يتوسع فقط: تُضاف مسارات وحقول جديدة، ولا يُحذف أو يُعاد تسمية شيء داخل v1. المسار الذي سيُزال يُعلَّم كمهمل قبل 12 شهرًا على الأقل من توقفه؛ وحتى ذلك الحين يعمل دون تغيير ويرد مع الترويستين Deprecation وSunset.
عميل TypeScript
يجري إعداد عميل TypeScript رسمي مولّد من مستند OpenAPI (دوال مُنمَّطة، إعادة المحاولة مع Retry-After، مفاتيح عدم التكرار، التصفح). وحتى نشره، يعمل أي مولّد OpenAPI مع openapi.json.
رموز الأخطاء
| الحالة | الرمز | المعنى |
|---|---|---|
400 | invalid_json | المحتوى ليس JSON صالحًا |
401 | unauthenticated | لم يُرسل مفتاح أو رمز |
401 | invalid_key | المفتاح غير معروف أو ملغى أو منتهٍ، أو استُخدم رمز MCP مع REST API |
401 | token_expired | انتهت صلاحية رمز التطبيق: جدّده |
403 | insufficient_scope | ينقص المفتاح النطاق الذي يحتاجه هذا المسار |
403 | forbidden | لا يحق لصاحب المفتاح فتح هذا القسم أو السجل |
403 | origin_not_allowed | استدعاء من متصفح لموقع ليس ضمن الأصول المسموح بها لمساحة العمل |
403 | ip_not_allowed | قائمة عناوين IP المسموح بها للمفتاح لا تتضمن هذا العنوان |
403 | test_mode_read_only | مفتاح اختبار حاول تغيير البيانات: مفاتيح الاختبار للقراءة فقط |
404 | not_found | لا يوجد سجل أو مسار كهذا في مساحة العمل |
409 | conflict | يتعارض الطلب مع الحالة الحالية، مثل التكرار |
422 | validation_failed | فشل التحقق من الحقول؛ تذكر الإجابة المشكلات لكل حقل |
429 | rate_limited | طلبات كثيرة جدًا: انتظر الثواني المذكورة في Retry-After |
500 | internal_error | حدث خطأ من جهتنا: أعد المحاولة لاحقًا واذكر X-Request-Id إذا تواصلت معنا |
المرجع أدناه باللغة الإنجليزية، مثل مستند OpenAPI.
Customers
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/customers | customers:read | List customers |
GET | /api/v1/customers/{id} | customers:read | Read a customer |
POST | /api/v1/customers | customers:write | Create a customer (an existing e-mail / phone returns that customer) |
PATCH | /api/v1/customers/{id} | customers:write | Update a customer's contact details |
Leads
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/inquiries | inquiries:read | List leads |
GET | /api/v1/inquiries/{id} | inquiries:read | Read a lead |
POST | /api/v1/inquiries | inquiries:write | Create a lead (contact, quote request, booking request, call-back) — notifies the team like the website form |
Quotations
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/quotations | quotations:read | List quotations |
GET | /api/v1/quotations/{id} | quotations:read | Read a quotation with its lines |
POST | /api/v1/quotations | quotations:write | Create a DRAFT quotation (tax computed by the workspace's rules) |
Invoices
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/invoices | invoices:read | List invoices |
GET | /api/v1/invoices/{id} | invoices:read | Read an invoice with lines and payments |
POST | /api/v1/invoices | invoices:write | Create a DRAFT invoice (numbered when issued in the back office) |
GET | /api/v1/payments | payments:read | List invoice payments (invoice=<id> to filter) |
GET | /api/v1/payments/{id} | payments:read | Read a payment |
Orders
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/orders | orders:read | List shop orders |
GET | /api/v1/orders/{id} | orders:read | Read a shop order |
Catalog
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/products | products:read | List products with price and stock (catalog:read also allows it) |
GET | /api/v1/products/{id} | products:read | Read a product |
GET | /api/v1/categories | catalog:read | List categories (type=product|service|post|project, locale=…) (مساحات العمل المستضافة) |
GET | /api/v1/services | catalog:read | List published services (مساحات العمل المستضافة) |
GET | /api/v1/services/{id} | catalog:read | Read a service (مساحات العمل المستضافة) |
GET | /api/v1/products/lookup | products:read | Exact barcode / SKU match (GTIN, SKU or an extra product barcode) — for scanners |
Bookings
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/booking-services | catalog:read | List bookable services (online booking on) (مساحات العمل المستضافة) |
GET | /api/v1/booking-services/{id} | catalog:read | Read a bookable service (مساحات العمل المستضافة) |
GET | /api/v1/bookings/slots | bookings:read | Free start times of a bookable service on a date (مساحات العمل المستضافة) |
GET | /api/v1/bookings | bookings:read | List appointments (مساحات العمل المستضافة) |
GET | /api/v1/bookings/{id} | bookings:read | Read an appointment (مساحات العمل المستضافة) |
POST | /api/v1/bookings | bookings:write | Book an appointment at a free time (409 when it was taken) (مساحات العمل المستضافة) |
Webhooks
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/events | webhooks:read | The webhook event catalog |
GET | /api/v1/deliveries | webhooks:read | Webhook delivery log |
GET | /api/v1/deliveries/{id} | webhooks:read | One delivery with its payload |
GET | /api/v1/webhooks | webhooks:read | List webhook endpoints (no secrets) (مساحات العمل المستضافة) |
POST | /api/v1/webhooks | webhooks:write | Create a webhook endpoint — the signing secret is returned once (مساحات العمل المستضافة) |
DELETE | /api/v1/webhooks/{id} | webhooks:write | Delete a webhook endpoint (مساحات العمل المستضافة) |
Account
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/me | (any) | Who is calling: the API key, or the person signed in to the app, with the workspace and the scopes |
Stock
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/warehouses | stock:read | Active stock locations |
GET | /api/v1/stock | stock:read | Stock levels per location (product=<id> for one product, all its rows) |
POST | /api/v1/stock/adjustments | stock:write | Add or remove stock (same rules as the admin: write-off reasons only remove) |
Appointments
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/appointments | appointments:read | List appointments (from / to filter the start time) |
GET | /api/v1/appointments/{id} | appointments:read | Read an appointment |
Point of sale
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/pos-sales | pos:read | List till sales and refunds (since = created since) |
GET | /api/v1/pos-sales/{id} | pos:read | Read a till sale with its lines and payments |
Tasks
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
GET | /api/v1/tasks | tasks:read | List tasks (app sign-in without tasks.manage: only my tasks) |
GET | /api/v1/tasks/{id} | tasks:read | Read a task |
POST | /api/v1/tasks | tasks:write | Create a task (assigned to the signed-in person by default) |
PATCH | /api/v1/tasks/{id} | tasks:write | Update a task or change its status (DONE closes it; recurring tasks schedule the next one) |
Files
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
POST | /api/v1/attachments | attachments:write | Upload a photo or PDF (multipart: file, taskId?, folder?) — images are re-encoded, metadata such as GPS removed |
GET | /api/v1/attachments/{id} | attachments:write | Read an uploaded file's record |
Apps
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
POST | /api/v1/session/handoff | (app) | One-time URL (60 s) that signs the app's web view in to the workspace and opens `next` (برمز التطبيق فقط) |
GET | /api/v1/devices | (app) | My app installations (برمز التطبيق فقط) |
POST | /api/v1/devices | (app) | Register an app installation for push (FCM / APNs / Huawei Push Kit token; the same token again returns the same id) (برمز التطبيق فقط) |
DELETE | /api/v1/devices/{id} | (app) | Remove an app installation (برمز التطبيق فقط) |
GET | /api/v1/devices/{id} | (app) | One app installation with the alert categories it does not get pushes for (برمز التطبيق فقط) |
PATCH | /api/v1/devices/{id} | (app) | Alert categories this installation does not get pushes for (tasks, sales, bookings, messages, stock, system) — they still appear in /notifications (برمز التطبيق فقط) |
GET | /api/v1/account/deletion | (app) | Delete account (apps): which path applies — workspace owner closes the workspace, staff ask the administrators, customers use the website — with links and a pending request (برمز التطبيق فقط) |
POST | /api/v1/account/deletion | (app) | Delete account (apps): mode request = ask the administrators to delete the staff account and remove the app data; mode app-data = only end every app sign-in and web session and remove devices / push tokens (برمز التطبيق فقط) |
POST | /api/v1/session/sign-out-all | (app) | Sign out of all devices: ends every app sign-in and web session of the person and removes their app installations (برمز التطبيق فقط) |
GET | /api/v1/rider/today | (app) | Rider mode: which duties I may start (rider = parcels.ride, tech = field.work, driver = fleet.drive), my duty, today's runs, delivery stops and pickups (برمز التطبيق فقط) |
POST | /api/v1/rider/duty | (app) | Start duty (returns a duty token that can only post positions / end the duty) or end it; the workspace's live-location setting must be on (برمز التطبيق فقط) |
POST | /api/v1/rider/positions | (app) | Post a batch of positions while on duty (app token or the duty token fx_dt_…); only the newest valid point is kept (latest position, no trail) and feeds the recipient ETA and the runs map; a driver's batch also moves their vehicle and, when the workspace keeps one, its short trail (برمز التطبيق فقط) |
GET | /api/v1/apps | (app) | Home screen of the apps: the app grid I may open (name, area, icon as SVG nodes, waiting count), the workspace brand and unread alerts (برمز التطبيق فقط) |
GET | /api/v1/search | (app) | Search records I may open (customers, invoices, orders, products …), grouped like the admin header search; also suggestion (did you mean), quick (prefilled create links such as a new invoice for a customer) and intent (برمز التطبيق فقط) |
GET | /api/v1/notifications | (app) | Alerts for me since a time (the desktop app polls this) (برمز التطبيق فقط) |
Sensors
| الطريقة | المسار | النطاق | ما الذي يفعله |
|---|---|---|---|
POST | /api/v1/sensors/readings | sensors:write | Upload sensor readings (temperature, humidity, fuel_level, value) — up to 500 per request; the device is the key's own device or the serial in `device`; re-sent readings are skipped; send an Idempotency-Key |
التالي: خطافات الويب
أحداث العمل تُرسل إلى نقطة HTTPS الخاصة بك، موقّعة ومعادة المحاولة ومسجّلة.