开始之前
- 有一个可用的租户账号（tenant_code + 用户名 + 密码）
- 能访问后端域名
操作步骤
先看 OpenAPI 文档
后端是 FastAPI，自带 OpenAPI。访问 {后端地址}/openapi.json 拿到完整端点与数据结构（当前 802 个路径、310 个 schema）。也可以用 Swagger UI（/docs）在线试调用。私有化部署时把地址换成你自己的域名。
拿 token
POST /api/auth/login，请求体四个字段里前三个必填：tenant_code（租户编码，不是企业名称）、username、password。可选 remember_me（延长 token 有效期，默认 false）与 captcha_id/captcha_code（开启验证码时必填）。返回 data.access_token。
带 token 调业务接口
所有业务接口要求请求头 Authorization: Bearer {access_token}。管理端接口前缀是 /api/admin/*，员工端是 /api/h5/*，平台总控是 /api/platform/*。租户隔离由服务端按 token 里的 tenant_id 自动完成，你不需要也不能传 tenant_id。
认清响应信封
所有接口都返回 {code, msg, data} 三层信封。成功时 code=200、msg 为空、data 是业务数据。注意：业务错误也返回 HTTP 200，但 body.code 不等于 200 —— 所以判断成败要看 body.code，不能只看 HTTP 状态码。唯一的例外是限流，回 HTTP 429。
分页只有 offset/limit
列表接口用 offset（从 0 开始）+ limit（默认 50，最大 200）翻页，返回 {items: [...]}。注意没有 total 字段 —— 需要总数就自己拉到底或按业务需要维护计数。limit 传超过 200 会被拒绝，别试。
错误处理要分三层
① HTTP 401：token 无效或过期（detail 会说「未登录」或「登录已失效」），重新登录；② HTTP 429：登录或调用过于频繁（登录限流是同一 IP + 租户编码 5 分钟 10 次），退避重试；③ HTTP 200 但 body.code ≠ 200：业务错误，msg 是给人看的原因，直接透传给用户即可。
一个完整的最小可运行示例
先登录拿 token，再用 token 拉订单。两次请求之间不需要别的动作，不需要签名，不需要额外头（除 Content-Type）。
代码示例
curl -X POST 'https://YOUR_HOST/api/auth/login' \
-H 'Content-Type: application/json' \
-d '{
"tenant_code": "YOUR_TENANT",
"username": "integration_bot",
"password": "********"
}'
# 返回
# {"code":200,"msg":"","data":{"access_token":"eyJhbGci...","token_type":"bearer"}}TOKEN='eyJhbGci...'
curl -s "https://YOUR_HOST/api/admin/production/orders?offset=0&limit=20" \
-H "Authorization: Bearer $TOKEN"import requests
BASE = "https://YOUR_HOST"
def login(tenant_code: str, username: str, password: str) -> str:
r = requests.post(f"{BASE}/api/auth/login", json={
"tenant_code": tenant_code,
"username": username,
"password": password,
}, timeout=15)
body = r.json()
if body.get("code") != 200:
raise RuntimeError(f"登录失败: {body.get('msg')}")
return body["data"]["access_token"]
def api_get(token: str, path: str, **params):
r = requests.get(f"{BASE}{path}", params=params,
headers={"Authorization": f"Bearer {token}"}, timeout=30)
if r.status_code == 429:
raise RuntimeError("触发限流，稍后重试")
body = r.json()
if body.get("code") != 200:
raise RuntimeError(f"业务错误 {body.get('code')}: {body.get('msg')}")
return body["data"]
if __name__ == "__main__":
tk = login("YOUR_TENANT", "integration_bot", "********")
page = api_get(tk, "/api/admin/production/orders", offset=0, limit=20)
for o in page["items"]:
print(o.get("code"), o.get("status"))示例中的域名、租户编码、密钥请替换成你自己的。生产环境不要把密钥写进前端代码。