Справочник API v1
Каждая точка REST API с методом, путём и нужной областью доступа, сгенерированная из того же документа OpenAPI, который отдаёт API.
GET https://<workspace>.zmle.com/api/v1/me
Быстрый старт
- Откройте мгновенное демо: рабочее пространство с примерными данными
- В демо откройте Админка → Интеграции и 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). Нативные и подключённые приложения используют 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.json работает любой генератор OpenAPI.
Коды ошибок
| Статус | Код | Значение |
|---|---|---|
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-точку: с подписью, повторами и журналом.