鉴权与通用约定

Base URL、Bearer JWT 鉴权、x-organization-id 组织头、分页与统一响应格式。

鉴权#

Docklify API 使用用户的 Supabase 会话鉴权。浏览器内 session cookie 即可；集成场景请传用户的 Supabase JWT：Authorization: Bearer <jwt>（2026-10-08 起支持，手机代理转发用户 token 即用此方式）。未登录返回 401。

BASE="https://saas.docklify.com/api"
TOKEN="<supabase-access-jwt>"
ORG="<organization-id>"

curl -s "$BASE/wms/inventory?page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-organization-id: $ORG" | jq .

组织范围#

几乎所有接口都是租户隔离的。用 x-organization-id 请求头（推荐）或 organization_id 查询参数传组织。非本组织成员返回 403；未传组织返回 400（WMS_VALID_001）。

分页#

列表接口接受 page 与 page_size（默认 20，最大 100；打印队列最大 200）。响应中带 meta: { total, page, page_size }。

响应格式#

成功返回 { ok: true, data, meta? }。WMS 错误返回 { code, message, details? }，HTTP 状态码取自错误码表（见错误码篇）。程序分支请依据 code，不要依赖 message 文案。

// success (HTTP 200)
{ "ok": true, "data": { "id": "…" }, "meta": { "total": 128, "page": 1, "page_size": 20 } }

// error (e.g. HTTP 409)
{ "code": "WMS_STOCK_001", "message": "库存可用量不足", "details": { "item_id": "…" } }