API v1 حوالہ
REST API کا ہر اینڈپوائنٹ اپنے میتھڈ، پاتھ اور مطلوبہ اسکوپ کے ساتھ، اسی OpenAPI دستاویز سے بنا جو API فراہم کرتا ہے۔
GET https://<workspace>.zmle.com/api/v1/me
فوری آغاز
- ایک فوری ڈیمو کھولیں: نمونہ ڈیٹا والا ورک اسپیس
- ڈیمو میں Admin → Integrations & API پر جا کر کلید بنائیں
- کلید کے ساتھ 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 (یا اس کا اپنا ڈومین)۔ API ہوسٹ https://api.zmle.com/v1 کلید سے ورک اسپیس تلاش کرتا ہے۔
تصدیق
کلید Authorization: Bearer <key> (یا X-Api-Key) میں بھیجیں۔ نیٹو اور منسلک ایپس PKCE کے ساتھ OAuth 2.1 اور مختصر مدت کے ایپ ٹوکن استعمال کرتی ہیں۔
فہرستیں اور صفحہ بندی
فہرستیں 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 ماہ پہلے deprecated نشان زد کیا جاتا ہے؛ تب تک وہ بغیر تبدیلی کے چلتا ہے اور Deprecation اور Sunset ہیڈر بھیجتا ہے۔
TypeScript کلائنٹ
OpenAPI دستاویز سے بنایا گیا ایک سرکاری TypeScript کلائنٹ تیار ہو رہا ہے (ٹائپڈ میتھڈ، Retry-After کے مطابق دوبارہ کوشش، idempotency key، صفحہ بندی)۔ شائع ہونے تک کوئی بھی OpenAPI جنریٹر openapi.json کے ساتھ کام کرتا ہے۔
ایرر کوڈز
| اسٹیٹس | کوڈ | مطلب |
|---|---|---|
400 | invalid_json | باڈی درست JSON نہیں ہے |
401 | unauthenticated | کوئی کلید یا ٹوکن نہیں بھیجا گیا |
401 | invalid_key | کلید نامعلوم، منسوخ یا ختم شدہ ہے، یا REST API پر MCP ٹوکن استعمال ہوا |
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 اینڈپوائنٹ پر بھیجے جاتے ہیں، دستخط شدہ، دوبارہ کوشش کیے گئے اور لاگ کیے گئے۔