开放接口设计说明

1. 接口请求模型

所有开放接口走同一套鉴权：请求头携带 AppKey、时间戳、随机串与签名。业务参数按动作不同，放在 Query（GET）或 JSON Body（POST）。

1.1 接口地址

1.2 系统级请求头（每个接口都必须）

兼容写法：也可用 Query/Form 传 app_key、timestamp、nonce、sign（优先读请求头）。

2. 应用 KEY 与密钥管理

3. 签名算法

3.1 待签名字符串

三行文本，用换行符 \n 连接（最后一行也要有，GET 无 Body 时第三行为空字符串）：

timestamp + "\n" + nonce + "\n" + rawBody

• timestamp：与请求头 X-Timestamp 完全一致
• nonce：与请求头 X-Nonce 完全一致
• rawBody：HTTP 原始请求体字节原文。GET 无 Body → 空字符串；POST 必须是发出去的那份 JSON 原文（空格、字段顺序都要一致）

3.2 计算公式

X-Sign = hex_lowercase( HMAC_SHA256( key=AppSecret, message=待签名字符串 ) )

3.3 手算示例（GET）

假设 AppSecret=skdemo，Timestamp=1730000000，Nonce=Ab12Cd34，GET 无 Body：

待签名 =
1730000000
Ab12Cd34
（第三行为空）

X-Sign = HMAC-SHA256("skdemo", "1730000000\nAb12Cd34\n")
       → 小写十六进制

3.4 手算示例（POST）

Body 原文为（注意一字不差）：

{"mch_id":0,"bill_type":"in","post_now":"1","lines":[{"goods_id":12,"attr_id_list":[3],"qty":10}]}

待签名 =
1730000000
Ab12Cd34
{"mch_id":0,"bill_type":"in","post_now":"1","lines":[{"goods_id":12,"attr_id_list":[3],"qty":10}]}

4. 公共约定

4.1 商家范围 mch_id

传入的 mch_id 必须属于该 AppKey 对应店铺，否则返回「商家不属于该店铺」。

4.2 统一返回结构

{
  "code": 0,
  "msg": "ok",
  "data": { }
}

5. 接口一览

跑腿、技师完整字段说明见：跑腿发单、技师发单。下文详细展开 ERP。

6. ERP 仓储接口

基础路径：/web/index.php?r=api/open/erp/{动作}。须先在对应商家或平台自营商品上开启「ERP 仓储」，库存单据才会写入；过账后小程序可售库存同步变化。

{
  "code": 0,
  "msg": "ok",
  "data": {
    "store_id": 1,
    "store_name": "示例店铺",
    "mch_id": 0,
    "erp_enabled": true
  }
}

{
  "code": 0,
  "msg": "ok",
  "data": [
    { "attr_id_list": [3, 8], "label": "红色 / L", "num": 20, "pic": "" }
  ]
}

{
  "mch_id": 0,
  "bill_type": "in",
  "remark": "采购到货",
  "post_now": "1",
  "lines": [
    {
      "goods_id": 12,
      "attr_id_list": [3, 8],
      "qty": 10,
      "unit_cost": 0,
      "remark": ""
    }
  ]
}

7. 跑腿发单（摘要）

完整参数与字段说明见 跑腿发单文档。基础路径：api/open/errand/{动作}，鉴权同第 3 节。

发单 Body 示例

{
  "out_order_no": "WB20261026001",
  "purchasing_type_id": 3,
  "fee": 12.5,
  "rider_fee": 8,
  "expect_minutes": 90,
  "content": "文件一份，请当面签收",
  "remark": "门禁密码 1208",
  "pickup": {
    "name": "张三", "mobile": "13800000000",
    "address": "深圳市南山区某某路 1 号",
    "lng": "113.93", "lat": "22.54"
  },
  "dropoff": {
    "name": "李四", "mobile": "13900000000",
    "address": "深圳市南山区某某大厦",
    "lng": "113.95", "lat": "22.53"
  }
}

8. 技师发单（摘要）

完整说明见 技师发单文档。基础路径：api/open/worker/{动作}。

发单 Body 示例

{
  "out_order_no": "HS20261026001",
  "goods_id": 18,
  "worker_id": 0,
  "fee": 128,
  "service_time": "2026-10-26 14:00:00",
  "content": "空调清洗一台",
  "customer": {
    "name": "王女士",
    "mobile": "13800000000",
    "address": "深圳市南山区某某路 1 号",
    "lng": "113.93",
    "lat": "22.54"
  }
}

9. 错误码与常见失败

10. 调用示例

10.1 PHP（推荐服务端）

<?php
$appKey = 'akxxxxxxxx';
$appSecret = 'skxxxxxxxxxxxxxxxx';
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(8));
$body = ''; // GET 为空；POST 时填 JSON 原文
$sign = hash_hmac('sha256', $timestamp . "\n" . $nonce . "\n" . $body, $appSecret);

$url = 'https://你的域名/web/index.php?r=api/open/erp/ping';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-App-Key: ' . $appKey,
        'X-Timestamp: ' . $timestamp,
        'X-Nonce: ' . $nonce,
        'X-Sign: ' . $sign,
    ],
]);
echo curl_exec($ch);

10.2 Node.js

const crypto = require('crypto');
const appKey = 'akxxxxxxxx';
const appSecret = 'skxxxxxxxxxxxxxxxx';
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = crypto.randomBytes(8).toString('hex');
const rawBody = ''; // POST 时用发出去的 JSON 字符串
const sign = crypto.createHmac('sha256', appSecret)
  .update(`${timestamp}\n${nonce}\n${rawBody}`).digest('hex');

fetch('https://你的域名/web/index.php?r=api/open/erp/ping', {
  headers: {
    'X-App-Key': appKey,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Sign': sign,
  }
}).then(r => r.json()).then(console.log);

10.3 curl（POST 库存）

# 先在脚本里算出 SIGN，BODY 必须与签名用的字符串一致
BODY='{"mch_id":0,"bill_type":"in","post_now":"1","lines":[{"goods_id":12,"attr_id_list":[3],"qty":10}]}'
curl -X POST "https://你的域名/web/index.php?r=api/open/erp/stock" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -H "X-App-Key: akxxxxxxxx" \
  -H "X-Timestamp: 1730000000" \
  -H "X-Nonce: Ab12Cd34Ef56" \
  -H "X-Sign: 算好的小写签名" \
  -d "$BODY"

相关文档

• 跑腿发单：场景、取送地址、抢单状态
• 技师发单：服务项目、上门时间、接单状态
• ERP 仓储管理（后台操作说明）
• 帮助中心