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

1. 概述与基础地址

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

生产基础地址（Base URL）：

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

能力范围

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

2. 对接准备与步骤

调用接口前请先完成以下步骤，与通用约定一起阅读。

3. 通用数据格式约定

为确保跨语言（Java / Python / Node / PHP 等）解析一致，平台对数据格式做如下统一约定：

3.1 编码与内容类型

• 请求与响应统一使用 UTF-8 编码。
• 请求体固定为 application/json（除 GET 查询外），请勿使用表单提交。
• 时间字段：会计月用 yyyy-MM（如 2026-09）；订单支付时间等时间戳用 yyyy-MM-dd HH:mm:ss，不带毫秒。

3.2 金额单位：一律以「分」整数返回 _fen

3.3 比率单位：一律以「基点 bp」整数返回

3.4 标识型字段（ID）与精度

• id / store_id / org_id / tenant_id 等标识字段为整型或字符串，请原样透传，不要在前端用浮点解析（如 JavaScript 的 Number() 对超长整型会丢失精度，建议以字符串处理或保持原类型）。
• 枚举/状态字段（如 status、doc_type、channel）为小写字符串，取值见各接口说明。

3.5 分页约定（当前版本）

为降低接入复杂度，当前版本多数接口返回全量匹配数据；部分高频写后查询接口采用「最近 N 条」截断：

4. 鉴权方式

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

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

用 client_id + client_secret 调用令牌接口换取短期 JWT（默认 1 小时有效），再以 JWT 调业务。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"

5. 请求头与公共参数

公共路径/查询参数

• :month / month：会计月份，格式 YYYY-MM（如 2026-09）。
• :store_id / store_id：门店 ID（整型，原样透传）。
• :org_id：组织编码，用于按组织定位门店利润。
• :months：趋势回溯月数（整型，上限 24）。

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

所有接口返回统一结构：

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

// 失败
{
  "code": 1,
  "bizCode": "APIKEY_INVALID",
  "message": "密钥凭证错误或已吊销",
  "data": null,
  "tenant_id": null
}

7. 错误码（bizCode）

业务失败时在响应 bizCode 返回，HTTP 状态码见下表：

8. 权限 Scope 矩阵

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

9.1 令牌换取

{
  "code": 0,
  "bizCode": "SUCCESS",
  "message": "ok",
  "data": {
    "access_token": "eyJ...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "profit:read,report:read"
  },
  "tenant_id": "tenant_xxxx"
}

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

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

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

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

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

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

10. 多语言对接示例

以下演示从「换取令牌 → 读取利润总览」的完整链路。示例中的 calay_... / sk_... 为占位，请替换为控制台实际密钥。

10.1 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（可选）：用 PAT 直连，跳过换令牌
curl https://open.calay.com.cn/api/open/v1/profit/stores \
  -H "Authorization: Bearer sk_替换为你的密钥"

10.2 Python（requests）

import requests, json

BASE = "https://open.calay.com.cn/api/open/v1"
CLIENT_ID = "calay_替换为你的ID"
CLIENT_SECRET = "sk_替换为你的密钥"

# 1) 换取令牌（建议缓存，到期前复用）
r = requests.post(f"{BASE}/oauth/token", json={
    "grant_type": "client_credentials",
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET,
})
token = r.json()["data"]["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# 2) 读取利润总览
dash = requests.get(f"{BASE}/profit/dashboard", headers=headers).json()
# 金额单位为「分」，换算成元：
for s in dash["data"]["stores"]:
    print(s["name"], "净利润(元)=", s["profit_fen"] / 100,
          "毛利率(%)=", s["gross_margin_bp"] / 100)

10.3 Node.js（fetch，Node 18+）

const BASE = "https://open.calay.com.cn/api/open/v1";
const CLIENT_ID = "calay_替换为你的ID";
const CLIENT_SECRET = "sk_替换为你的密钥";

// 1) 换取令牌
const t = await fetch(`${BASE}/oauth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ grant_type: "client_credentials", client_id: CLIENT_ID, client_secret: CLIENT_SECRET }),
}).then(r => r.json());
const token = t.data.access_token;

// 2) 读取门店列表
const stores = await fetch(`${BASE}/profit/stores`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json());
console.log(stores.data.list);

11. 限流与配额矩阵

为保障服务稳定，开放接口按下列规则限流（超出返回 HTTP 429，建议指数退避重试）：

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

12. 常见问题与红线

Q1：金额字段为什么是「分」而不是「元」？

为避免浮点精度问题（如 1.005 元被误算为 1.00 元），平台内部与开放接口统一以最小货币单位「分」整数传递。展示时除以 100 即可。仅「报表中心」的月报/薪资/发票三类接口为便于直接展示，已将金额格式化为「元」字符串（字段名不含 _fen）。

Q2：比率字段为什么是「基点 bp」？

同理，gross_margin_bp（毛利率）、dividend_bp（分红比例）等以「万分之一」整数传递，除以 100 即百分比。避免浮点比较误差。

Q3：支持回调 / Webhook 推送吗？

当前开放 API 为拉取（pull）模式，暂不支持事件回调推送。如需近实时数据，请按业务节奏轮询对应读接口。

Q4：为什么渠道订单没有分页参数？

当前版本渠道订单返回最近 200 条（按渠道过滤同理），未做游标分页。如需全量历史，请在控制台导出或联系技术支持。

红线提醒