统一供货 API

用车玖账号下单,按会员供货价扣车玖钱包。同步商品和库存,查询订单,并接收发货和服务进度。

查询车玖钱包GET
https://chejiu.vip/openapi/v1/balance
{ "ok": true, "balance": "50.00", "currency": "CNY" }示例响应

快速开始

  1. 申请凭证在车玖用户中心申请 API 凭证。审核通过后,在店铺服务端保存 API Key 和 Secret。新签发凭证可用于下列三种协议,已有长凭证可继续用于独角兽。
  2. 配置地址交易请求发往 https://chejiu.vip。选择下方与你的店铺匹配的协议。
  3. 联调订单先查钱包并同步商品。再核对 SKU、会员供货价和回调,确认一笔小额订单的金额与交付。

通用 API

路径前缀为 /openapi/v1。每次请求通过 HTTPS 发送 X-Api-Key 和 X-Api-Secret。有 JSON 请求体时设置 Content-Type: application/json。

cURL · 查询钱包
curl --silent --show-error \
  'https://chejiu.vip/openapi/v1/balance' \
  -H "X-Api-Key: ${CHEJIU_API_KEY}" \
  -H "X-Api-Secret: ${CHEJIU_API_SECRET}"

将环境变量配置到服务端。保管 Secret,生产日志应遮盖鉴权头和异次元表单里的 app_key。

独角兽

原生对接以 https://chejiu.vip 为站点地址,路径前缀为 /api/v1/upstream。服务端代码可以按下列规则生成请求签名。

  • Dujiao-Next-Api-Key 携带车玖 API Key。
  • Dujiao-Next-Timestamp 携带 Unix 秒级时间戳。时钟偏差上限为 60 秒。
  • Dujiao-Next-Signature 携带以 API Secret 为密钥的 HMAC-SHA256 小写十六进制签名。
Python · 签名并查询钱包
import hashlib, hmac, os, time
from urllib.request import Request, urlopen

method = "POST"
path = "/api/v1/upstream/ping"
body = b""
timestamp = str(int(time.time()))
canonical = "\n".join([method, path, timestamp, hashlib.md5(body).hexdigest()])
key = os.environ["CHEJIU_API_KEY"]
secret = os.environ["CHEJIU_API_SECRET"].encode()
signature = hmac.new(secret, canonical.encode(), hashlib.sha256).hexdigest()
request = Request("https://chejiu.vip" + path, data=body, method=method, headers={
    "Dujiao-Next-Api-Key": key,
    "Dujiao-Next-Timestamp": timestamp,
    "Dujiao-Next-Signature": signature,
    "User-Agent": "CheJiuMerchant/1.0",
})
with urlopen(request, timeout=10) as response:
    print(response.read().decode())

签名用 URL 路径,省略查询参数。正文按发送的原始字节计算 MD5,空正文也计算摘要。签名后发送同一份正文。

异次元

原版自动发卡

在原版异次元中添加货源站点 https://chejiu.vip,将车玖 API Key 和 Secret 分别填入商户 ID 和商户密钥。已验证异次元 3.8.6 的 CNY 单规格本地自动卡密商品。使用原版客户端同步商品和库存、下单并取得卡密。

增强接口

人工发货、服务单和异步上游采购使用 POST /shared/chejiu/v1。下游集成代码要能接收待交付状态,并在回调或查单后更新自己的订单。

表单为 application/x-www-form-urlencoded,含 app_id、app_key、operation、payload 和 sign。用异次元 Str::generateSignature 签名前四项。payload 为无填充的 Base64URL 编码 UTF-8 JSON 对象,编码前上限为 16 KiB。

操作JSON 对象
balance、categories{}
products{"page":1,"page_size":50}
product{"product_id":12}
quote、trade使用下方报价、下单的 JSON。
query{"downstream_order_no":"SHOP-1001"}
下载 PHP 客户端示例

接口一览

以下路径拼在对应前缀后。通用前缀为 /openapi/v1,独角兽前缀为 /api/v1/upstream。

方法与路径用途
GET /balance · 通用
POST /ping · 独角兽
验证凭证、查钱包余额。
GET /categories查询商品分类。
GET /products
GET /products/{id}
同步商品、SKU、供货价和库存。列表支持 page、page_size、updated_after 和 include_inactive。
POST /member-quote
POST /member-quotes
查询单个或批量会员供货价。锁价用单笔报价并携带下游订单号。
POST /products/{id}/manual-fields/{field_key}/validate
POST /products/{id}/service-objects/validate
发送 {"value":…} 校验本地人工商品字段,或发送 {"quantity":1,"service_objects":[…]} 校验本地服务商品。
POST /orders用车玖钱包下单。
GET /orders/by-request/{request_no}
GET /orders/{id}
按原下游订单号或车玖订单 ID 查单。发货结果可通过查单取得。

报价与订单

下游顾客向你的店铺付款。你的店铺向车玖采购,车玖从该凭证所属账号的钱包扣会员供货价。金额字段为十进制字符串,保存时使用十进制金额类型。

获取锁价凭证

POST /member-quote · 请求示例
{
  "sku_id": 701,
  "quantity": 1,
  "downstream_order_no": "SHOP-1001"
}

读取 unit_amount、total_amount、currency、quote_token 和 quote_expires_at。锁价有效 15 分钟,绑定凭证、下游订单号、SKU 和数量。报价阶段尚未预留库存。订单受理后按受理金额履约。

提交订单

POST /orders · 请求示例
{
  "sku_id": 701,
  "quantity": 1,
  "downstream_order_no": "SHOP-1001",
  "quote_token": "从单笔报价接口取得",
  "callback_url": "https://merchant.example.com/chejiu/callback"
}

使用新凭证直接下单时,省略 quote_token 即按受理时的会员价结算。人工和服务商品按商品返回的表单结构填入 manual_form_data。下游订单号可以包含 1 至 64 个 ASCII 字母、数字、点、下划线、冒号和连字符。原版异次元沿用客户端的 32 位字母数字订单引用。

下单响应中以 ok 判断是否受理。保留 order_id、order_no、status、amount 和 currency 供履约和对账。钱包扣款失败并已取消时,可能返回 HTTP 200 与 ok:false。

发货与回调

paid 或 fulfilling 表示仍应等候交付。处理发货或服务进度时,读取查单返回的 status、fulfillment 与 service_progress。处理取消和退款时核对原订单及 refund_records。

提交 callback_url 后,车玖向你的 HTTPS 地址发送 JSON 通知。车玖负责按自己的商品映射向上游采购,并将对应的结果通知你的店铺。

通知事件为 order.status_changed 或 order.fulfilled。等待回调时可以按原订单号查单。回调日志应遮盖卡密和客户信息。

  1. 验证签名读取三个 Dujiao-Next-* 请求头,使用原始正文验签,验证时间戳和所属凭证。回调的签名路径固定为 /api/v1/upstream/callback。
  2. 按原单核对核对 order_id、downstream_order_no 和状态,必要时以鉴权查单结果为准。服务进度可用 callback_version 避免旧通知覆盖新状态。
  3. 落库后确认按原订单幂等更新。处理完成后返回 HTTP 200 和 {"ok":true}。接收方需能处理重复通知。

错误与重试

请求超时先查原单。保留原下游订单号、原商品与报价。遇到超时、503 或状态不明时,先按原号查询。在核对扣款前避免创建新订单号。

HTTP 或错误码处理方式
401 / 403核对凭证、审核和启用状态。签名协议还要核对时间戳及签名。
402 · insufficient_balance核对并补足车玖钱包余额。
409 · quote_expired确认原订单仍未受理,再获取新报价。
409 · insufficient_stock更新该 SKU 的库存,再决定是否继续销售。
409 · order_reference_conflict同一引用已用于其他请求。先查询原引用并核对订单。
429降低请求频率。查询和同步应退避,订单提交先查原单。
503 · order_requires_review保留原订单号,使用同一凭证查单并核对余额。

独角兽、通用和异次元增强接口用 HTTP 状态与 ok、error_code 表示结果。异次元原版按客户端原有的 code 与 msg 处理。