当前位置: API文档
trade_push.php(创建原始订单)
1.1 接口描述:①推送销售订单给ERP ;②更新已推送成功的销售订单。 |
| 1.2 注意事项:仅支持推送自有/其它平台店铺 |
| 1.3 订单更新:已推送成功的销售订单的订单状态、退款状态、订单信息变更到ERP情况比较复杂,订单变更处理办法详解, 单击这里【必看】 |
| 1.4 调用建议:建议每间隔(5~10)分钟,将商城积累的订单集中推送,每次请求包含订单条数建议不超过50条(1条订单由“trade_list+order_list”构成),如果累积量超过了50条,分多次请求。 |
| 2.1 自研商城、分销系统、全渠道等系统对接 |
| 环境 | HTTP地址 |
|---|---|
| 测试环境 | https://openapitest.huice.com/openapi/trade_push.php |
| 正式环境 | https://openapi.huice.com/openapi/trade_push.php |
| 名称 | 字段 | 类型 | 长度 | 必须 | 描述 |
|---|---|---|---|---|---|
| 卖家账号 | sid | String | 是 | 购买ERP时由旺店通分配给ERP购买方,请从ERP购买方获取。 | |
| 接口账号 | appkey | String | 是 | 本开放平台“自助对接”功能模块内自助申请,申请流程单击这里 | |
| 时间戳 | timestamp | int | 是 | 北京时间1970-01-01 08:00:00起至现在的总秒数,10位int值,旺店通企业版API服务端允许请求最大时间误差为5min,date.timezone = Asia/Shanghai。 | |
| 签名 | sign | String | 是 | API输入参数签名结果,签名算法介绍单击这里 |
| 名称 | 字段 | 类型 | 长度 | 必须 | 描述 |
|---|---|---|---|---|---|
| 店铺编号 | shop_id | int | 10 | 是 | 代表店铺所有属性的唯一编码,用于店铺区分,ERP内支持自定义(ERP店铺界面设置,查看路径ERP→设置→基本设置→店铺→店铺列表),用于创建指定店铺单据信息,测试环境店铺编号信息同接口账号。ERP内shop_no对应的“店铺平台”必须为“自有/其它”。正式环境店铺创建成功后ERP会自动授权,如果自动授权失败,在ERP店铺界面(路径ERP→设置→基本设置→店铺→店铺列表)选中授权失败的店铺,点击店铺界面提供的店铺授权按钮重新授权。 |
| 订单列表节点 | trade_list | data[] | 是 | 请求参数的1级数据节点,包含销售订单所有属性信息的数据节点,节点下数据字段详见下述“trade_list” |
trade_list
| 名称 | 字段 | 类型 | 长度 | 必须 | 描述 |
|---|---|---|---|---|---|
| 原始单号 | tid | varchar | 40 | 是 | 指商城、官网等平台的订单编号,ERP称之为原始单号,同一个sid下通过本接口新增订单的tid保证唯一。 |
| 平台状态 | trade_status | tinyint | 4 | 是 | 平台订单状态较多且涉及变更,平台订单状态:10待支付 30已支付 40 部分发货 50已发货 70已完成 80已退款 90已关闭(付款前取消) |
| 支付状态 | pay_status | tinyint | 4 | 否 | 平台订单付款状态:0:未付款,1:部分付款,2:已付款 |
| 发货条件 | delivery_term | tinyint | 4 | 是 | 1:款到发货,2:货到付款(包含部分货到付款),3:分期付款 |
| 下单时间 | trade_time | datetime | 否 | 平台订单创建时间,时间格式:yyyy-MM-dd HH:mm:ss | |
| 支付时间 | pay_time | datetime | 是 | 平台订单付款时间,时间格式:yyyy-MM-dd HH:mm:ss,未付款订单为:0000-00-00 00:00:00 | |
| 客户网名 | buyer_nick | varchar | 100 | 是 | 平台买家昵称,注意:一次推送网名相同的订单不能超过30 |
| 买家email | buyer_email | varchar | 60 | 否 | 买家email |
| 收件人 | receiver_name | varchar | 40 | 是 | 收件人姓名 |
| 省份 | receiver_province | varchar | 40 | 是 | 收件人省份,传为中文名称需与旺店通地址库匹配,点击查看 |
| 城市 | receiver_city | varchar | 40 | 是 | 收件人城市,传为中文名称需与旺店通地址库匹配,点击查看 |
| 区县 | receiver_district | varchar | 40 | 是 | 收件人区县,传为中文名称需与旺店通地址库匹配,点击查看 |
| 地址详情 | receiver_address | varchar | 256 | 是 | 收件人地址详情,传为中文名称,需与旺店通地址库匹配,点击查看,如果不传省市区,则会尝试从详细地址解析省市区,必须是空格分隔的才能解析成功,需要注意直辖市的地址格式,举例“北京 北京市 海淀区 花园路xxxx” |
| 手机 | receiver_mobile | varchar | 40 | 是 | 手机号码 |
| 电话 | receiver_telno | varchar | 40 | 否 | 电话号码 |
| 邮编 | receiver_zip | varchar | 20 | 否 | 收件人邮编 |
| 物流方式 | logistics_type | smallint | 6 | 否 | 不传本参数,输入值默认-1,表示由ERP系统策略选择。平台指定订单发货物流可选输入值单击这里 |
| 发票类别 | invoice_kind | tinyint | 4 | 否 | 0:不需要,1:普通发票,2:增值税普通发票电子,3:增值税普通发票纸质,4:增值税专用发票 |
| 发票抬头 | invoice_title | varchar | 255 | 否 | 发票抬头 |
| 发票内容 | invoice_content | varchar | 255 | 否 | 常见内容:纳税人识别号、地址、电话、开户银行、银行账户,按照以下格式推送,系统开发票时可解析。 推送格式:纳税人识别号:xxxxxxxxxxx;地址:xxxxxxxx 13888888888;开户银行:银行名称 银行账户; 英文分号以后是地址,地址后面是空格,空格后面是电话,电话后面是英文分号,分号以后是开户行,然后空格,然后是银行账号 |
| 客户备注标旗 | seller_flag | tinyint | 4 | 客户备注标旗,取值0至5对应的标旗颜色依次为灰(无标旗)、红、黄、绿、蓝、紫,不传默认0 | |
| 买家备注 | buyer_message | varchar | 1024 | 否 | 买家下单时填写的订单备注 |
| 客服备注 | seller_memo | varchar | 1024 | 否 | 商家客服对订单进行的备注内容 |
| 标旗 | seller_flag | tinyint | 4 | 否 | 客服标旗,取值0至5对应的标旗颜色依次为灰(无标旗)、红、黄、绿、蓝、紫,不传默认0 |
| 邮费 | post_amount | decimal | (19,4) | 是 | 商家收取买家的物流或者快递费用 |
| 货到付款金额 | cod_amount | decimal | (19,4) | 是 | 货到付款金额 即cod金额 |
| 货到付款买家费用 | ext_cod_fee | decimal | (19,4) | 是 | 货到付款买家费用,扣除货到付款订单金额后,卖家仍需支付的货到付款其他金额。这个钱卖家收不回来,是快递公司直接收走,但在快递单里是要打印出来,否则快递收款就错了 |
| 其它收费 | other_amount | decimal | (19,4) | 是 | 其它应从买家收取的服务费,其他费用 |
| 已付 | paid | decimal | (19,4) | 是 | 订单已付金额,即消费者实际付款金额。传参后,系统会自动分摊到子单上。 |
| 自动流转模式 | is_auto_wms | tinyint | 1 | 否 | 是否为自动流转模式(1:是 0:不是 不传默认0),非自动流转模式一定不要传值。自动流转模式处理办法,”自动流转模式处理办法详解”)单击这里 |
| 订单货品明细节点 | order_list | data[] | 是 | 货品明细列表(子订单列表)节点 |
order_list
| 名称 | 字段 | 类型 | 长度 | 必须 | 描述 |
|---|---|---|---|---|---|
| 子订单编号 | oid | varchar | 40 | 是 | 平台订单货品表主键,子订单唯一标识,同一个sid下通过本接口新增订单的oid(子订单编号)要保证唯一;如果oid重复,ERP生成系统单(递交)时会提示“订单货品数量不一致xxxxxx” |
| 数量 | num | decimal | (19,4) | 是 | 货品数量,订单推送成功以后本字段值不能更改 |
| 单价 | price | decimal | (19,4) | 是 | 标价,折扣前的价格,可以推送价格为0的商品。订单推送成功以后本字段值不能更改 |
| 状态 | status | tinyint | 4 | 是 | 平台子订单状态,子订单状态可以和主订单不一样,比如其中一个子订单退款完成,其状态是80,但主订单仍然是待发货,可选值同trade_status |
| 退款状态 | refund_status | tinyint | 4 | 是 | 0:无退款,1:取消退款,2:已申请退款,3:等待退货,4:等待收货,5:退款成功。本字段在售前退款的时候,根据不同的场景填写不同的值,eg:申请退款值为2,取消退款值为1…… |
| 平台货品ID | goods_id | varchar | 40 | 是 | 平台系统货品(SPU)的唯一标识。goods_id不能为空,goods_id和goods_no区别与SPU、SKU概念介绍,单击这里 |
| 平台规格ID | spec_id | varchar | 40 | 否 | 平台系统单品(SKU)的的唯一标识,尽量不为空,spec_id和spec_no区别与SPU、SKU概念介绍,单击这里 |
| 货品编码 | goods_no | varchar | 40 | 否 | 平台货品SPU编码,对应ERP货品编号,尽量不为空 |
| 规格编码 | spec_no | varchar | 40 | 是 | 平台货品SKU唯一码,对应ERP商家编码,goods_no和spec_no不能同时为空 |
| 货品名称 | goods_name | varchar | 255 | 是 | 平台货品名称 |
| 规格名称 | spec_name | varchar | 100 | 否 | 平台货品规格名称 |
| 调整 | adjust_amount | decimal | (19,4) | 是 | 客服调整总金额(大于0加价,小于0减价,是折扣来源的一部分,没有传0) |
| 优惠 | discount | decimal | (19,4) | 是 | 下单总折扣,客户下单时折扣(比如促销打折,不包含客服调整、分摊折扣,没有传0) |
| 分摊优惠 | share_discount | decimal | (19,4) | 是 | 分摊总折扣,由总订单分摊而来,一般是付款时产生,如使用优惠券,没有传0。分摊优惠传值注意:例如三个商品,优惠10,分摊优惠可以是:3/3/4,或者3.33/3.33/3.34.即最后一个商品的分摊优惠使用减法计算 |
| 备注 | remark | varchar | 1024 | 否 | 货品明细备注 |
| 名称 | 字段 | 类型 | 长度 | 必须 | 描述 |
|---|---|---|---|---|---|
| 错误码 | code | int | 40 | 是 | 状态码:0表示成功,其他表示失败 |
| 错误原因 | message | varchar | 255 | 是 | 错误原因 |
| 返回的新增订单个数 | new_count | int | 10 | 否 | 有单据新增时不为0(新建的原始单据) |
| 返回的更新订单个数 | chg_count | int | 10 | 否 | 有单据更新时不为0(在已有的原始单据上进行修改) |
6.响应示例
| JSON | {
'code': 0,
'message': "",
'new_count': 1,
'chg_count': 0
} |
| JSON | {
"code": 99,
"message": "buyer_nick 名字不能只用一个,不同客户必须用不同的名字"
} |