ERP API（Shop Response）文档汇总

1. 接口概述

ERP API（Shop Response）是 OMS 系统提供的接收方接口，用于接收第三方平台（如淘宝、天猫、京东等）推送的业务数据。本文档汇总了所有接收方接口的详细信息，包括订单、售后、换货、商品、发票、支付等业务接口。

接口方向：第三方平台 → OMS 系统（接收方）

与 OpenAPI 的区别：

OpenAPI：OMS 系统对外提供接口，供外部系统调用 OMS 功能（查询、操作等）
ERP API（Shop Response）：第三方平台推送数据到 OMS，OMS 作为接收端处理数据

2. API 调用基础

2.1 请求方式

所有接口均支持 POST 方式请求。

2.2 请求URL

http(s)://[域名]/index.php/api

2.3 系统级参数

所有接口请求必须包含以下系统级参数：

参数名	类型	必选	描述
flag	string	是	接入标识，固定值：`erpapi`
app_id	string	是	应用ID，如：`ecos.ome`
certi_id	string	是	证书ID，系统证书编号
from_node_id	string	是	来源节点ID，推送方节点ID
node_id	string	是	目标节点ID，店铺节点ID（OMS节点）
node_type	string	是	节点类型，如：`ecos.ome`
timestamp	int	是	时间戳，10位时间戳（单位：秒）
method	string	是	接口方法名，格式：`{app_id}.{resource}.{action}`，如：`ome.order.add`
sign	string	是	签名，用于验证请求合法性，详见签名算法章节
format	string	否	响应格式，可选值：`json`（默认）
v	string	否	API版本号，如：`1.0`

3. 签名算法

3.1 签名生成步骤

收集所有请求参数（不包括 sign 本身）
按照参数名的 ASCII 码顺序进行排序（ksort）
递归拼接参数名和参数值（对于嵌套数组，递归处理）
对拼接后的字符串进行 MD5 加密，再转大写
将上一步的结果与 token（接口密钥）拼接
再次进行 MD5 加密并转大写，得到最终签名

3.2 签名生成公式

sign = strtoupper(md5(strtoupper(md5(assemble($params))). $token))

3.3 签名算法要点

参与签名的参数集合不包含 sign 本身
参数按键名排序后按约定拼装
首次 MD5 后转大写，与 token 拼接后再 MD5，最终再转大写
保持编码一致（UTF-8）、去除多余空白
对于布尔值，转换为 1 或 0
对于嵌套数组，递归处理

3.4 签名算法代码示例（PHP）

php

/**
 * 生成签名算法函数
 *
 * @param $params
 * @param $token
 * @return string
 */
function gen_sign($params, $token)
{
    return strtoupper(md5(strtoupper(md5(assemble($params))). $token));
}

/**
 * 组装签名参数
 *
 * @param $params
 * @return string|null
 */
function assemble($params)
{
    if (!is_array($params)) {
        return null;
    }
    
    // ksort
    ksort($params);
    
    // sign
    $sign = '';
    foreach ($params as $key => $val)
    {
        if (is_null($val)) {
            continue;
        }
        
        if (is_bool($val)) {
            $val = ($val) ? 1 : 0;
        }
        
        $sign .= $key . (is_array($val) ? assemble($val) : $val);
    }
    
    return $sign;
}

/**
 * 系统参数
 *
 * @param $flag
 * @return array
 */
function system_params($flag)
{
    $params['flag'] = $flag;
    $params['type'] = 'json';
    $params['charset'] = 'utf-8';
    $params['ver'] = '1';
    $params['timestamp'] = time();
    
    return $params;
}

// erpapi标识
$flag = 'erpapi';

// token：config目录下certi.php中获取(没有则为空)
$token = 'your_interface_key';

//set params
$setParams = array(
    'app_id' => 'ecos.b2c', //ecos.ome
    'node_type' => 'ecos.ome',
    'callback_url' => '', //回调url
    'certi_id' => '20215858518', //证书ID
    'from_node_id' => '20218888', //节点ID
    'node_id' => '1311861837', //店铺节点node_id
);

// 系统级参数
$systemParams = system_params($flag);
$systemParams = array_merge($systemParams, $setParams);

// 请求参数
$requestParams = array();

// 组装请求参数
$params = array_merge($systemParams, $requestParams);

// 生成签名
$params['sign'] = gen_sign($params, $token);

4. 接口响应格式

4.1 响应格式说明

所有接口响应格式统一为 JSON，包含以下字段：

字段名	类型	必填	说明
rsp	string	是	响应状态：`succ`（成功）或 `fail`（失败）
msg	string	是/否	响应消息（成功时包含操作描述，失败时包含错误信息）
data	object	否	响应数据（成功时可能包含订单号、售后单号等信息，失败时可能包含错误详情）

4.2 成功响应示例

json

{
    "rsp": "succ",
    "msg": "订单创建成功！订单ID：12345",
    "data": {
        "tid": "2526959714656153498"
    }
}

4.3 失败响应示例

json

{
    "rsp": "fail",
    "msg": "创建失败：格式化数据为空"
}

5. 系统级错误码

错误码	描述	可能原因
E_PARAM	参数缺失或格式不正确	必填参数缺失、参数类型错误
E_STATE	业务状态不允许	订单状态不允许当前操作、未发货订单不接收换货等
E_DUPLICATE	重复提交/版本未变化	订单已存在、版本号未变化等
E_AMOUNT	金额校验不通过	退款金额超过订单金额、金额不一致等
E_VERSION	版本未变化/时间戳未更新	售后版本号未变化、时间戳无效等
E_INTERNAL	内部处理异常	数据库错误、系统异常等
E_EMPTY	数据为空	换货明细不可为空、订单明细不可为空等
E_SIGN	签名错误	签名算法错误、token 不正确等

6. 支持的接口模块列表

6.1 order（订单）

接口名：订单接口
请求方法：POST
功能描述：订单新增、状态/支付/发货更新、备注与标记维护
主要方法：

接口方法	功能描述
`ome.order.add`	新增/更新订单（依据 lastmodify 与是否存在决定 create/update）
`ome.order.status_update`	更新订单状态（仅接收作废 dead，版本>1 其他状态不接收）
`ome.order.pay_status_update`	更新订单支付状态（版本2不走此接口）
`ome.order.ship_status_update`	更新订单发货状态（版本2不走此接口）
`ome.order.custom_mark_add`	新增订单买家备注
`ome.order.custom_mark_update`	更新订单买家备注
`ome.order.memo_add`	新增订单商家备注与旗标
`ome.order.memo_update`	更新订单商家备注与旗标
`ome.order.payment_update`	更新订单支付方式与金额调整

文档链接：order.md

6.2 aftersalev2（售后）

接口名：售后接口（v2）
请求方法：POST
功能描述：售后单创建、物流更新，覆盖退款/退货/换货流程
主要方法：

接口方法	功能描述
`ome.aftersalev2.add`	新增/更新售后单（退款/退货/换货）
`ome.aftersalev2.logisticsUpdate`	更新售后物流信息

文档链接：aftersalev2.md

6.3 exchange（换货）

接口名：换货接口
请求方法：POST
功能描述：换货单创建与明细处理
主要方法：

接口方法	功能描述
`ome.exchange.add`	新增换货单

文档链接：exchange.md

6.4 goods（商品）

接口名：商品接口
请求方法：POST
功能描述：商品/SPU 与 SKU 同步，奥翔渠道扩展操作
主要方法：

接口方法	功能描述
`ome.goods.add`	新增商品/SPU 与 SKU
`ome.goods.delete`	删除商品
`ome.goods.sku_delete`	删除 SKU
`ome.goods.aoxiang_update`	奥翔渠道商品更新
`ome.goods.aoxiang_combine_update`	奥翔组合商品更新
`ome.goods.aoxiang_delete`	奥翔渠道商品删除
`ome.goods.aoxiang_mapping`	奥翔商品映射维护

文档链接：goods.md

6.5 invoice（发票）

接口名：发票接口
请求方法：POST
功能描述：发票信息创建与消息推送
主要方法：

接口方法	功能描述
`ome.invoice.add`	新增发票信息（与订单关联）
`ome.invoice.message_push`	发票消息推送

文档链接：invoice.md

6.6 payment（支付）

接口名：支付接口
请求方法：POST
功能描述：支付单创建、支付状态更新
主要方法：

接口方法	功能描述
`ome.payment.add`	新增支付记录（带金额/订单状态校验）
`ome.payment.statusUpdate`	支付状态更新（仅允许 succ）

文档链接：payment.md

6.7 qianniu（千牛）

接口名：千牛接口
请求方法：POST
功能描述：订单地址修改、SKU 修改等
主要方法：

接口方法	功能描述
`ome.qianniu.address_modify`	订单地址修改
`ome.qianniu.modifysku`	明细 SKU 修改（换码/改规格）
`ome.qianniu.order_addr_modify`	订单收货地址修改（别名/兼容接口）

文档链接：qianniu.md

6.8 branch（分单）

接口名：分单接口
请求方法：POST
功能描述：分单等待/占用控制
主要方法：

接口方法	功能描述
`ome.branch.wait`	分单等待/占用控制

文档链接：branch.md

6.9 delivergoods（发货）

接口名：发货接口
请求方法：POST
功能描述：发货加急、发货承诺处理
主要方法：

接口方法	功能描述
`ome.delivergoods.urgent`	发货加急/催发
`ome.delivergoods.promise`	发货承诺/时效处理

文档链接：delivergoods.md

7. 接口调用示例

7.1 PHP 示例（创建订单接口）

php

<?php
/**
 * 模拟 erpapi 接口创建订单
 */

// API 参数
$erp_api_url = 'http://www.example.com/index.php/api';
$flag = 'erpapi'; // erpapi 标识
$token = '899ffcd610e80f117c77d86de578ac430742f5abd5815736b7b29abd0ed5e88fd'; // config目录下certi.php中获取（没有则为空）

// 系统级参数设置
$set_params = array();
$set_params['app_id'] = 'ecos.ome';
$set_params['certi_id'] = '20215858518'; // 证书ID
$set_params['from_node_id'] = '20218888'; // 来源节点ID
$set_params['node_type'] = 'ecos.ome';
$set_params['node_id'] = '1311861837'; // 店铺节点ID（查询 sdb_ome_shop 表找到 node_id）

// 业务参数
$str = '{
    "order_bn": 2526959714656153498,
    "status": "active",
    "total_amount": 177,
    "cost_item": 414,
    "pmt_goods": 207,
    "pmt_order": 30,
    "cur_amount": 177,
    "payed": 177,
    "pay_status": 1,
    "ship_status": 0,
    "order_source": "taobao",
    "date": "2025-10-11 17:48:22",
    "createtime": 1744339314,
    "modified": 1744364899,
    "lastmodify": 1744364899,
    "consignee": {
        "name": "陈**",
        "area_state": "浙江省",
        "area_city": "嘉兴市",
        "area_district": "海盐县",
        "addr": "通*镇**村西三**号",
        "zip": 314300,
        "mobile": "***********",
        "telephone": "",
        "email": ""
    },
    "member_info": {
        "name": "c**",
        "uname": "c**",
        "tel": "",
        "mobile": "",
        "email": "",
        "area_state": "",
        "area_city": "",
        "area_district": "",
        "addr": "",
        "zip": ""
    },
    "order_objects": [
        {
            "bn": "887350098396",
            "oid": 2526959714656153600,
            "name": "电动工具12V锂电池1.5Ah/2.0Ah适配12V机器5120",
            "quantity": 3,
            "price": 138,
            "amount": 414,
            "divide_order_fee": 177,
            "status": "active",
            "order_items": [
                {
                    "bn": "887350098396",
                    "quantity": 3,
                    "price": 138,
                    "amount": 414,
                    "divide_order_fee": 177,
                    "pmt_price": 207
                }
            ]
        }
    ],
    "payments": [
        {
            "paymethod": "支付宝",
            "money": 177,
            "pay_time": "2025-10-11 17:48:19",
            "trade_no": 2024002526959714656153498
        }
    ],
    "shipping": {
        "shipping_name": "快递",
        "cost_shipping": 0,
        "is_cod": "false"
    }
}';

// 解析 JSON 字符串为数组
$postdata = json_decode($str, true);

// 将数组类型的参数转换为 JSON 字符串（组件会自动解码）
foreach ($postdata as $key => $postVal) {
    if (is_array($postdata[$key])) {
        $postdata[$key] = json_encode($postdata[$key]);
    }
}

// 设置接口方法
$postdata['method'] = 'ome.order.add';
$postdata['ship_status'] = '0';

// 删除已经配置的参数（避免重复）
unset($postdata['sign'], $postdata['app_id'], $postdata['from_node_id'], $postdata['node_id']);

// 删除不需要的字段
unset($postdata['task_id'], $postdata['_FROM_MQ_QUEUE'], $postdata['task_type'], 
      $postdata['taskmgr_sign'], $postdata['auto_combine']);
unset($postdata['o2o_info'], $postdata['is_service_order'], $postdata['is_pt'], 
      $postdata['cost_tax'], $postdata['tax_title']);

// 生成系统基础参数
function system_params($flag) {
    $params['flag'] = $flag;
    $params['type'] = 'json';
    $params['charset'] = 'utf-8';
    $params['ver'] = '1';
    $params['timestamp'] = time();
    return $params;
}

// 合并所有参数
$params = system_params($flag);
$params = array_merge($params, $set_params);
$params = array_merge($params, $postdata);

// 递归拼接参数（用于签名）
function assemble($params)
{
    if (!is_array($params)) {
        return null;
    }
    
    ksort($params);
    $sign = '';
    foreach ($params as $key => $val) {
        if (is_null($val)) {
            continue;
        }
        
        if (is_bool($val)) {
            $val = ($val) ? 1 : 0;
        }
        
        $sign .= $key . (is_array($val) ? assemble($val) : $val);
    }
    
    return $sign;
}

// 生成签名算法函数
//@todo：签名不对一般是：$token 填写的与 config/certi.php 不一致
function gen_sign($params, $token) {
    return strtoupper(md5(strtoupper(md5(assemble($params))). $token));
}

// 生成签名
$params['sign'] = gen_sign($params, $token);

// 发送请求
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $erp_api_url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
$return = curl_exec($ch);
curl_close($ch);

// 处理响应
$result = json_decode($return, true);

echo('<pre>');
print_r($result);
exit;
?>

示例说明：

系统参数设置：certi_id、from_node_id、node_id 等需要从 OMS 系统配置中获取
业务参数处理：数组类型参数需要 JSON 编码，组件会自动解码
参数清理：删除签名、重复的系统参数和不需要的业务字段
签名生成：使用 assemble() 和 gen_sign() 函数生成签名，注意 token 必须与 config/certi.php 中的配置一致
错误排查：如果签名错误，请检查 token 是否与服务器配置一致

7.2 接口调用流程

准备参数：组装系统级参数和业务参数
生成签名：使用签名算法生成 sign 参数
发送请求：通过 POST 方式发送到 /index.php/api
处理响应：解析返回的 JSON 数据，判断 rsp 字段

8. 注意事项

签名安全：请妥善保管接口密钥（token），避免泄露。签名不对时，请检查 token 是否与 config/certi.php 中的配置一致。
时间戳：timestamp 必须为 10 位时间戳（Unix 时间戳，单位：秒），建议与服务器时间保持同步。
参数格式：数组类型参数可以 JSON 字符串形式传递，组件会自动解码为数组格式。
幂等性：建议使用 method + node_id + order_bn（订单）或 method + node_id + refund_bn（售后）等组合作为幂等键，避免重复提交。
数据校验：系统会进行多重校验（版本校验、金额校验、状态校验等），如不符合条件将返回失败。
组件处理：部分接口（如订单）的数据会经过组件层进行格式化处理，详见各接口文档说明。
版本差异：不同 API 版本（如版本1、版本2）对某些接口的支持可能不同，请参考具体接口文档。
编码要求：所有参数和响应均使用 UTF-8 编码。

9. 快速导航

按业务类型分类：

业务类型	接口模块	文档链接
订单管理	order	order.md
售后管理	aftersalev2	aftersalev2.md
换货管理	exchange	exchange.md
商品管理	goods	goods.md
发票管理	invoice	invoice.md
支付管理	payment	payment.md
订单维护	qianniu	qianniu.md
分单控制	branch	branch.md
发货管理	delivergoods	delivergoods.md

10. 附录

10.1 数据脱敏说明

部分敏感数据（如客户姓名、手机号、地址等）在接收时可能已进行脱敏处理，系统会根据 index_field 中的 oaid 等索引进行解密或关联处理。

10.2 调用频率限制

为保证系统稳定性，接口调用可能存在频率限制，具体限制规则请联系系统管理员获取。

10.3 接口版本说明

版本1（v1）：传统接口版本，支持完整的支付单、状态更新等接口
版本2（v2）：新版本接口，部分状态更新接口不再使用（如支付状态、发货状态更新）

10.4 组件化处理说明

部分接口（如订单接口）的数据会经过组件层进行格式化处理，组件包括：

master - 订单主表信息
items - 订单明细
shipping - 配送信息
consignee - 收货人信息
member - 会员信息
tax - 税务信息

详细组件处理逻辑请参考各接口文档。

架构

性能

Shop Response（第三方平台推送接口）

WMS Response（第三方WMS推送接口）

ERP API（Shop Response）文档汇总

1. 接口概述

2. API 调用基础

2.1 请求方式

2.2 请求URL

2.3 系统级参数

3. 签名算法

3.1 签名生成步骤

3.2 签名生成公式

3.3 签名算法要点

3.4 签名算法代码示例（PHP）

4. 接口响应格式

4.1 响应格式说明

4.2 成功响应示例

4.3 失败响应示例

5. 系统级错误码

6. 支持的接口模块列表

6.1 order（订单）

6.2 aftersalev2（售后）

6.3 exchange（换货）

6.4 goods（商品）

6.5 invoice（发票）

6.6 payment（支付）

6.7 qianniu（千牛）

6.8 branch（分单）

6.9 delivergoods（发货）

7. 接口调用示例

7.1 PHP 示例（创建订单接口）

7.2 接口调用流程

8. 注意事项

9. 快速导航

10. 附录

10.1 数据脱敏说明

10.2 调用频率限制

10.3 接口版本说明

10.4 组件化处理说明

ERP API（Shop Response）文档汇总 ​

1. 接口概述 ​

2. API 调用基础 ​

2.1 请求方式 ​

2.2 请求URL ​

2.3 系统级参数 ​

3. 签名算法 ​

3.1 签名生成步骤 ​

3.2 签名生成公式 ​

3.3 签名算法要点 ​

3.4 签名算法代码示例（PHP） ​

4. 接口响应格式 ​

4.1 响应格式说明 ​

4.2 成功响应示例 ​

4.3 失败响应示例 ​

5. 系统级错误码 ​

6. 支持的接口模块列表 ​

6.1 order（订单） ​

6.2 aftersalev2（售后） ​

6.3 exchange（换货） ​

6.4 goods（商品） ​

6.5 invoice（发票） ​

6.6 payment（支付） ​

6.7 qianniu（千牛） ​

6.8 branch（分单） ​

6.9 delivergoods（发货） ​

7. 接口调用示例 ​

7.1 PHP 示例（创建订单接口） ​

7.2 接口调用流程 ​

8. 注意事项 ​

9. 快速导航 ​

10. 附录 ​

10.1 数据脱敏说明 ​

10.2 调用频率限制 ​

10.3 接口版本说明 ​

10.4 组件化处理说明 ​

ERP API（Shop Response）文档汇总

1. 接口概述

2. API 调用基础

2.1 请求方式

2.2 请求URL

2.3 系统级参数

3. 签名算法

3.1 签名生成步骤

3.2 签名生成公式

3.3 签名算法要点

3.4 签名算法代码示例（PHP）

4. 接口响应格式

4.1 响应格式说明

4.2 成功响应示例

4.3 失败响应示例

5. 系统级错误码

6. 支持的接口模块列表

6.1 order（订单）

6.2 aftersalev2（售后）

6.3 exchange（换货）

6.4 goods（商品）

6.5 invoice（发票）

6.6 payment（支付）

6.7 qianniu（千牛）

6.8 branch（分单）

6.9 delivergoods（发货）

7. 接口调用示例

7.1 PHP 示例（创建订单接口）

7.2 接口调用流程

8. 注意事项

9. 快速导航

10. 附录

10.1 数据脱敏说明

10.2 调用频率限制

10.3 接口版本说明

10.4 组件化处理说明