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 एंडपॉइंट पर भेजे जाते हैं, साइन किए, दोबारा कोशिश किए और लॉग किए हुए।