咖莱翼开放平台 · 开放 API 对接文档

1. 概述与基础地址

开放 API 用于让您的自有系统（ERP、BI、财务中台等）以机器对机器（M2M）方式安全读取或写入咖莱翼各业务数据。所有接口均为 HTTPS，返回统一 JSON 信封。

生产基础地址（Base URL）：

https://open.calay.com.cn/api/open/v1

能力范围

利润中心（读/写） 人事中心（读） 报表中心（读） 渠道订单（读） 共享商业（读）

2. 鉴权方式

每个请求必须在 Authorization 头携带 Bearer 令牌。支持两种获取/携带方式：

方式 A：OAuth2 client_credentials（推荐服务端调用）

用 client_id + client_secret 调用令牌接口换取短期 JWT（默认 1 小时有效），再以 JWT 调业务。

# 1) 换取令牌
curl -X POST https://open.calay.com.cn/api/open/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "calay_a6856eec8010e5fa87d93084",
    "client_secret": "sk_336a257b366abb9a8410c502099f1761fe38fb3d61d4e297"
  }'

# 2) 用返回的 access_token 调业务
curl https://open.calay.com.cn/api/open/v1/profit/dashboard \
  -H "Authorization: Bearer <access_token>"

方式 B：PAT 个人访问令牌（sk_ 直连）

直接用密钥本身（sk_ 前缀）作为 Bearer 令牌调用业务，无需先换 JWT，适合简单脚本。

curl https://open.calay.com.cn/api/open/v1/profit/dashboard \
  -H "Authorization: Bearer sk_336a257b366abb9a8410c502099f1761fe38fb3d61d4e297"

3. 响应格式（统一信封）

所有接口返回统一结构：

// 成功
{
  "code": 0,
  "bizCode": "SUCCESS",
  "message": "ok",
  "data": { ... },
  "tenant_id": "tenant_xxxx"
}

// 失败
{
  "code": 1,
  "bizCode": "APIKEY_INVALID",
  "message": "client_id or client_secret invalid",
  "data": null,
  "tenant_id": null
}

4. 错误码（bizCode）

5. 权限 Scope 矩阵

密钥创建时按以下 scope 子集授权，调用对应接口时由网关强制校验：

5.1 令牌换取

5.2 密钥管理（控制台内操作）

5.3 利润中心（scope: profit:read / profit:write）

5.4 人事中心（scope: hr:read）

5.5 报表中心（scope: report:read）

5.6 渠道订单（scope: channel:read）

5.7 共享商业（scope: sb:read）

6. 完整对接示例（curl）

以下演示从「换取令牌 → 读取利润总览 → 读取月度报表」的完整链路：

# 步骤 1：换取访问令牌
TOKEN=$(curl -s -X POST https://open.calay.com.cn/api/open/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"calay_替换为你的ID","client_secret":"sk_替换为你的密钥"}' \
  | python -c "import sys,json;print(json.load(sys.stdin)['data']['access_token'])")

# 步骤 2：读取利润总览
curl https://open.calay.com.cn/api/open/v1/profit/dashboard \
  -H "Authorization: Bearer $TOKEN"

# 步骤 3：读取 2026-09 月度利润报表
curl "https://open.calay.com.cn/api/open/v1/report/profit-month/2026-09" \
  -H "Authorization: Bearer $TOKEN"

# 步骤 4（可选）：用 PAT 直连，跳过换令牌
curl https://open.calay.com.cn/api/open/v1/profit/stores \
  -H "Authorization: Bearer sk_替换为你的密钥"

7. 限流与最佳实践

• 令牌缓存：JWT 默认 1 小时有效，请在服务端缓存并重用，避免每次请求都换取（换取接口限流 20 次/分钟/IP）。
• 最小权限：为每个对接系统创建独立密钥，仅授予所需 scope；下线时及时吊销。
• 密钥保管：client_secret 等同密码，请勿写入前端代码或公开仓库；泄露立即吊销。
• 错误重试：遇 401/403 先检查 scope 与令牌有效性；遇网络错误采用指数退避重试。
• 时间参数：所有月份参数统一 YYYY-MM 格式。