API v1 reference
Bawat endpoint ng REST API kasama ang method, path at kailangang scope nito, ginawa mula sa parehong OpenAPI document na ibinibigay ng API.
GET https://<workspace>.zmle.com/api/v1/me
Mabilis na simula
- Magbukas ng instant demo: isang workspace na may sample data
- Sa demo, pumunta sa Admin → Integrations & API at gumawa ng key
- Tawagan ang GET /api/v1/me gamit ang key (nasa ibaba) para makita kung kaninong workspace at tao ito
- Magdagdag ng webhook endpoint at pumili ng mga event; sa demo, naitatala ang delivery pero hindi ipinapadala
OpenAPI document
Pampubliko ang buong specification; hindi kailangan ng key para basahin ito: https://zmle.com/api/v1/openapi.json
curl https://<your-demo>.zmle.com/api/v1/me \ -H "Authorization: Bearer $ZMLE_API_KEY"
Base address
Sumasagot ang bawat workspace sa sarili nitong address: https://<workspace>.zmle.com/api/v1 (o sa sarili nitong domain). Hinahanap ng API host na https://api.zmle.com/v1 ang workspace mula sa key.
Authentication
Ipadala ang key bilang Authorization: Bearer <key> (o X-Api-Key). Gumagamit ang mga native at nakakonektang app ng OAuth 2.1 na may PKCE at mga panandaliang app token.
Mga listahan at paging
Tumatanggap ang mga listahan ng page at per (1–100, default 25), q para sa paghahanap at since para sa mga pagbabago pagkatapos ng isang petsa. May total at pages ang sagot, pati ang mga header na Link at X-Total-Count.
Mga error
JSON ang mga error: { error: { code, message } } kasama ang HTTP status. May X-Request-Id ang bawat sagot. Tumatanggap ang mga POST request ng header na Idempotency-Key. May bucket ang bawat key na 300 request na napupuno nang 5 bawat segundo; ipinapakita ng X-RateLimit-Remaining ang natitira, at may kasamang Retry-After ang 429.
Mga bersyon at deprecation
Lumalaki lang ang v1: nagdadagdag ng bagong ruta at field, walang inaalis o pinapalitan ng pangalan sa loob ng v1. Ang rutang aalisin ay minamarkahang deprecated nang hindi bababa sa 12 buwan bago ito huminto; hanggang doon, gumagana ito nang walang pagbabago at sumasagot nang may Deprecation at Sunset na header.
TypeScript client
Inihahanda ang opisyal na TypeScript client na ginawa mula sa OpenAPI document (typed na method, pag-ulit na sumusunod sa Retry-After, idempotency key, paging). Hangga't hindi pa ito nailalabas, gumagana ang anumang OpenAPI generator sa openapi.json.
Mga error code
| Status | Code | Kahulugan |
|---|---|---|
400 | invalid_json | Hindi valid na JSON ang body |
401 | unauthenticated | Walang ipinadalang key o token |
401 | invalid_key | Hindi kilala, na-revoke o expired ang key, o ginamit ang MCP token sa REST API |
401 | token_expired | Expired na ang app token: i-refresh ito |
403 | insufficient_scope | Walang scope ang key na kailangan ng route na ito |
403 | forbidden | Hindi puwedeng buksan ng tao ng key ang bahaging ito o record |
403 | origin_not_allowed | Browser call mula sa site na wala sa allowed origins ng workspace |
403 | ip_not_allowed | Wala ang address na ito sa IP allow-list ng key |
403 | test_mode_read_only | Sinubukan ng test key na baguhin ang data: nagbabasa lang ang mga test key |
404 | not_found | Walang ganitong record o route sa workspace na ito |
409 | conflict | Sumasalungat ang request sa kasalukuyang estado, gaya ng duplicate |
422 | validation_failed | Bumagsak sa validation ang mga field; nakalista sa sagot ang problema ng bawat field |
429 | rate_limited | Masyadong maraming request: maghintay ng mga segundong nasa Retry-After |
500 | internal_error | May pumalya sa panig namin: subukan muli mamaya at banggitin ang X-Request-Id kung kokontakin mo kami |
Nasa English ang reference sa ibaba, gaya ng OpenAPI document.
Customers
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
GET | /api/v1/orders | orders:read | List shop orders |
GET | /api/v1/orders/{id} | orders:read | Read a shop order |
Catalog
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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=…) (mga hosted workspace) |
GET | /api/v1/services | catalog:read | List published services (mga hosted workspace) |
GET | /api/v1/services/{id} | catalog:read | Read a service (mga hosted workspace) |
GET | /api/v1/products/lookup | products:read | Exact barcode / SKU match (GTIN, SKU or an extra product barcode) — for scanners |
Bookings
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
GET | /api/v1/booking-services | catalog:read | List bookable services (online booking on) (mga hosted workspace) |
GET | /api/v1/booking-services/{id} | catalog:read | Read a bookable service (mga hosted workspace) |
GET | /api/v1/bookings/slots | bookings:read | Free start times of a bookable service on a date (mga hosted workspace) |
GET | /api/v1/bookings | bookings:read | List appointments (mga hosted workspace) |
GET | /api/v1/bookings/{id} | bookings:read | Read an appointment (mga hosted workspace) |
POST | /api/v1/bookings | bookings:write | Book an appointment at a free time (409 when it was taken) (mga hosted workspace) |
Webhooks
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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) (mga hosted workspace) |
POST | /api/v1/webhooks | webhooks:write | Create a webhook endpoint — the signing secret is returned once (mga hosted workspace) |
DELETE | /api/v1/webhooks/{id} | webhooks:write | Delete a webhook endpoint (mga hosted workspace) |
Account
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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` (app token lang) |
GET | /api/v1/devices | (app) | My app installations (app token lang) |
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) (app token lang) |
DELETE | /api/v1/devices/{id} | (app) | Remove an app installation (app token lang) |
GET | /api/v1/devices/{id} | (app) | One app installation with the alert categories it does not get pushes for (app token lang) |
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 (app token lang) |
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 (app token lang) |
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 (app token lang) |
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 (app token lang) |
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 (app token lang) |
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 (app token lang) |
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 (app token lang) |
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 (app token lang) |
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 (app token lang) |
GET | /api/v1/notifications | (app) | Alerts for me since a time (the desktop app polls this) (app token lang) |
Sensors
| Method | Path | Scope | Ano ang ginagawa |
|---|---|---|---|
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 |
Susunod: Mga webhook
Mga business event na ipinapadala sa HTTPS endpoint mo, naka-sign, inuulit at naka-log.