CJ 文档中心

# 开发必读

  • 开发文档说明
  • 对接流程
  • 接口调用流程
  • 基本调试方法
  • 调用频率限制

# 开发文档说明

服务端API开放了丰富的能力接口，开发者可以借助接口能力，实现企业服务及企业微信的集成。支持的能力，通过目录导航可以快速预览， 目录树按功能块聚合归类，如通讯录管理、消息推送等。

文档的阅读次序，建议先阅读一遍开发指南，以及接口 access_token 获取。然后就可以独立查看各个功能块文档说明。

所有的接口需使用 HTTPS 协议、JSON 数据格式、UTF8 编码。接口说明格式如下：

请求方式：POST（HTTPS）
接口说明：
...
请求地址：
...
请求包体：
...
参数说明：
...
权限说明：
...
返回结果：
...
参数说明：
...
  1. 请求方式，标明接口调用的 HTTP 方法，区分 GET/POST 请求。所有的请求都为 https 协议。
  2. 请求地址，注意大小写。
  3. 请求包体/参数说明，标明请求参数示例及说明，参数说明包括字段含义、取值范围，开发者在设计数据结构时，应参考该定义范围。
  4. 权限说明，标明接口的使用范围，默认只能看当前账户下的数据，暂时没有开发者特别留意调用场景。
  5. 返回结果/参数说明，标明返回参数示例及说明。特别留意，所有接口在调用失败时返回包里都有 code、message（部分接口在调用 成功时没有返回 code 和 message）。 开发者需根据 code 存在且既不为 200 也不为 0 判断为失败，否则为成功（部分接口成功时 code 为 0）（code意义请见全局错误码）。 而 message 仅作参考，后续可能会有变动，因此不可作为是否调用成功的判据。

# 对接流程

接入 CJ API 按下面 6 步进行，点击图中的步骤可跳转到对应文档。灰色虚线框为可选步骤。

flowchart LR
    S1["① 获取 API Key"] --> S2["② 获取 Access Token"] --> S3["③ 沙盒测试"] --> S4["④ 同步商品"] --> S5["⑤ 下单与支付<br/>（按场景选）"] --> S6["⑥ 物流与售后"]
    classDef optional fill:#f5f5f5,stroke:#999,stroke-dasharray:4 3,color:#666
    class S3 optional
    click S1 "/zh/api/start/apikey.html"
    click S2 "/zh/api/start/token.html"
    click S3 "/zh/api/start/sandbox.html"
    click S4 "/zh/api/start/Products-Synchronization-Processing.html"
    click S5 "/zh/api/start/Orders-Synchronization-Processing.html"
    click S6 "/zh/api/api2/api/logistic.html"
步骤 要做什么 关键接口 / 文档
① 获取 API Key 安装 API 应用，在 API 页面创建 API Key 如何获取API Key
② 获取 Access Token 用 API Key 换取 Token，在服务端缓存，快过期时刷新 getAccessToken / refreshAccessToken，流程见下方「接口调用流程」，接口见鉴权接口
③ 沙盒测试（可选） 创建订单时传 isSandbox=1，不真实扣款、不真实履约 沙盒机制
④ 同步商品 获取商品列表、详情与变体，查询实时库存；可订阅商品 / 库存 Webhook 商品同步流程、Webhook 机制
⑤ 下单与支付 运费试算、创建订单、余额支付或在 MyCJ 网站支付；按业务选择对应的下单场景 订单同步流程、订单接口
⑥ 物流与售后 查询物流轨迹或接收订单 / 物流 Webhook；有问题时发起纠纷 物流接口、纠纷接口

整个流程中的所有调用都受调用频率与点数规则约束，见接口调用限制与点数资源规则。

# 接口调用流程

flowchart TD
    A([开始]) --> B{"服务端缓存中有有效的 Access Token？"}
    B -- 否 --> C["用 API Key 获取 Access Token<br/>POST /authentication/getAccessToken"]
    C --> D["在服务端缓存 accessToken / refreshToken / 过期时间"]
    D --> E
    B -- 是 --> E["调用业务接口<br/>请求头 CJ-Access-Token: accessToken"]
    E --> F{"HTTP 200 且 code 为 200 或 0？"}
    F -- 是 --> G([处理返回数据])
    F -- "否，code = 1600001<br/>（token 无效或过期）" --> H["刷新 Access Token<br/>POST /authentication/refreshAccessToken"]
    H --> I{"刷新成功？"}
    I -- 是 --> D
    I -- "否，code = 1600003<br/>（refresh token 无效）" --> C
    F -- "否，其他 code" --> J(["按错误码处理<br/>见全局错误码"])

获取 access_token，参考说明：文档说明

  1. 缓存和刷新 access_token。
  2. 开发者需要缓存 access_token，用于后续接口的调用。当 access_token 失效或过期时，需要重新获取。
  3. 调用具体的业务接口

Access Token 与 Refresh Token 的有效期均为 180 天。错误码说明见全局错误码。

# 基本调试方法

可以借助工具排查问题原因。参考说明：文档说明

# 调用频率限制

出于系统保护的考虑，我们对接口的调用做了频率限制。参考说明：主动调用频率限制

← 如何获取API Key →