跳到正文
14 天免费试用,无需银行卡9 种语言176 种业务类型 · 50 个应用
ZH· USD
试用在线演示免费试用

API v1 参考

REST API 的每个端点及其方法、路径和所需权限范围,由 API 自身提供的同一份 OpenAPI 文档生成。

GET https://<workspace>.zmle.com/api/v1/me

快速入门

  1. 打开即时演示:一个带示例数据的工作区
  2. 在演示中进入 管理 → 集成与 API 并创建密钥
  3. 用密钥调用 GET /api/v1/me(见下方),查看它属于哪个工作区和哪个人
  4. 添加 Webhook 端点并选择事件;在演示中投递只会记录,不会发送

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 个月标记为已弃用;在此之前它照常工作,并在响应中带有 Deprecation 和 Sunset 标头。

TypeScript 客户端

根据 OpenAPI 文档生成的官方 TypeScript 客户端正在准备中(类型化方法、遵循 Retry-After 的重试、幂等键、分页)。在发布之前,任何 OpenAPI 生成器都可以使用 openapi.json。

错误代码

状态代码含义
400invalid_json请求体不是有效的 JSON
401unauthenticated未发送密钥或令牌
401invalid_key密钥未知、已吊销或已过期,或在 REST API 上使用了 MCP 令牌
401token_expired应用令牌已过期:请刷新
403insufficient_scope密钥缺少此路由所需的权限范围
403forbidden密钥所属的人无权打开此区域或记录
403origin_not_allowed来自不在工作区允许来源列表中的网站的浏览器调用
403ip_not_allowed此密钥的 IP 允许列表不包含该地址
403test_mode_read_only测试密钥尝试更改数据:测试密钥只能读取
404not_found此工作区中没有该记录或路由
409conflict请求与当前状态冲突,例如重复
422validation_failed字段校验失败;响应会按字段列出问题
429rate_limited请求过多:请等待 Retry-After 中的秒数
500internal_error我们这边出现故障:请稍后重试,联系我们时请提供 X-Request-Id

下方参考与 OpenAPI 文档一样为英文。

Customers

方法路径权限范围功能
GET/api/v1/customerscustomers:readList customers
GET/api/v1/customers/{id}customers:readRead a customer
POST/api/v1/customerscustomers:writeCreate a customer (an existing e-mail / phone returns that customer)
PATCH/api/v1/customers/{id}customers:writeUpdate a customer's contact details

Leads

方法路径权限范围功能
GET/api/v1/inquiriesinquiries:readList leads
GET/api/v1/inquiries/{id}inquiries:readRead a lead
POST/api/v1/inquiriesinquiries:writeCreate a lead (contact, quote request, booking request, call-back) — notifies the team like the website form

Quotations

方法路径权限范围功能
GET/api/v1/quotationsquotations:readList quotations
GET/api/v1/quotations/{id}quotations:readRead a quotation with its lines
POST/api/v1/quotationsquotations:writeCreate a DRAFT quotation (tax computed by the workspace's rules)

Invoices

方法路径权限范围功能
GET/api/v1/invoicesinvoices:readList invoices
GET/api/v1/invoices/{id}invoices:readRead an invoice with lines and payments
POST/api/v1/invoicesinvoices:writeCreate a DRAFT invoice (numbered when issued in the back office)
GET/api/v1/paymentspayments:readList invoice payments (invoice=<id> to filter)
GET/api/v1/payments/{id}payments:readRead a payment

Orders

方法路径权限范围功能
GET/api/v1/ordersorders:readList shop orders
GET/api/v1/orders/{id}orders:readRead a shop order

Catalog

方法路径权限范围功能
GET/api/v1/productsproducts:readList products with price and stock (catalog:read also allows it)
GET/api/v1/products/{id}products:readRead a product
GET/api/v1/categoriescatalog:readList categories (type=product|service|post|project, locale=…) (托管工作区)
GET/api/v1/servicescatalog:readList published services (托管工作区)
GET/api/v1/services/{id}catalog:readRead a service (托管工作区)
GET/api/v1/products/lookupproducts:readExact barcode / SKU match (GTIN, SKU or an extra product barcode) — for scanners

Bookings

方法路径权限范围功能
GET/api/v1/booking-servicescatalog:readList bookable services (online booking on) (托管工作区)
GET/api/v1/booking-services/{id}catalog:readRead a bookable service (托管工作区)
GET/api/v1/bookings/slotsbookings:readFree start times of a bookable service on a date (托管工作区)
GET/api/v1/bookingsbookings:readList appointments (托管工作区)
GET/api/v1/bookings/{id}bookings:readRead an appointment (托管工作区)
POST/api/v1/bookingsbookings:writeBook an appointment at a free time (409 when it was taken) (托管工作区)

Webhooks

方法路径权限范围功能
GET/api/v1/eventswebhooks:readThe webhook event catalog
GET/api/v1/deliverieswebhooks:readWebhook delivery log
GET/api/v1/deliveries/{id}webhooks:readOne delivery with its payload
GET/api/v1/webhookswebhooks:readList webhook endpoints (no secrets) (托管工作区)
POST/api/v1/webhookswebhooks:writeCreate a webhook endpoint — the signing secret is returned once (托管工作区)
DELETE/api/v1/webhooks/{id}webhooks:writeDelete 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/warehousesstock:readActive stock locations
GET/api/v1/stockstock:readStock levels per location (product=<id> for one product, all its rows)
POST/api/v1/stock/adjustmentsstock:writeAdd or remove stock (same rules as the admin: write-off reasons only remove)

Appointments

方法路径权限范围功能
GET/api/v1/appointmentsappointments:readList appointments (from / to filter the start time)
GET/api/v1/appointments/{id}appointments:readRead an appointment

Point of sale

方法路径权限范围功能
GET/api/v1/pos-salespos:readList till sales and refunds (since = created since)
GET/api/v1/pos-sales/{id}pos:readRead a till sale with its lines and payments

Tasks

方法路径权限范围功能
GET/api/v1/taskstasks:readList tasks (app sign-in without tasks.manage: only my tasks)
GET/api/v1/tasks/{id}tasks:readRead a task
POST/api/v1/taskstasks:writeCreate a task (assigned to the signed-in person by default)
PATCH/api/v1/tasks/{id}tasks:writeUpdate a task or change its status (DONE closes it; recurring tasks schedule the next one)

Files

方法路径权限范围功能
POST/api/v1/attachmentsattachments:writeUpload a photo or PDF (multipart: file, taskId?, folder?) — images are re-encoded, metadata such as GPS removed
GET/api/v1/attachments/{id}attachments:writeRead 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/readingssensors:writeUpload 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

下一步: Webhook

业务事件发送到您的 HTTPS 端点,带签名、自动重试并记录日志。

Webhook