贸易对接规范订单.docx

E贸易订单信息对接规范

当前状态：
草稿

当前版本：
1.1
发布
ü
发布日期：
2023-5-12
修改历史
日期
版本
作者
修改内容
评审号
变更控制号
2023-3-24
1.0
吴建业

2023-5-12
1.1
吴建业

目录
1 文档说明 1
2 对接流程 1
2.1 对接流程图 1
2.2 对接流程说明 1
3 数据传输体系架构 2
4 接口规范 2
4.1 接口使用说明 2
4.2 安全机制 2
4.3 接口报文 3
4.3.1 报文规则和系统限定 3
4.3.2 接口请求测试地址URL 3
4.3.3 订单信息格式 3
4.3.4 订单信息字段说明 6
4.3.5 报文结构示例 12
4.3.6 请求报文字段说明 12
4.3.7 回执报文字段说明 13
4.3.8 数据加密说明 13

1 文档说明
本文档描述电商公司与E贸易系统对接的操作流程，数据传输的架构体系，以及电商公司在与E贸易系统进行对接的相关接口规范和说明。
2 对接流程
2.1 对接流程图

2.2 对接流程说明
1)、电商公司备案在海关国检进行公司备案完毕之后，海关会提供电商公司一个数据传输加密KEY。
2）、电商需要准备一台服务器，加密KEY插到该服务器上，作为数据传输中转设备；其中该服务器可以托管到河南保税物流中心机房，也可以由电商公司自己管理维护。
3）、如服务器托管到河南保税物流中心机房，需要向河南保税物流中心下属部门信息中心硬件网络组提交服务器配置清单，作为设备移交的依据；该设备在物权上归属于电商公司，使用权归属河南保税物流中心。
4）、如电商公司自己管理维护服务器，需保证服务器长期不能关机，另需要提供远程控制权限，由河南保税中心技术人员远程登录该服务器进行相关数据传输软件的安装。
5）、电商公司根据该文档提供的接口规范以及说明进行程序开发，并测试，假如开发测试完毕，即可以对接正式环境。
3 数据传输体系架构

4 接口规范

4.1 接口使用说明
1) 报文通讯方式为HTTP通讯,E贸易提供URL给电商公司调用，电商公司根据此接口规范约定的方式传入参数和值。
2) E贸易根据规范实时返回结果，客户根据结果拟定是否需要重传。
4.2 安全机制
传输数据采用RSA非对称加密算法，密钥对由E贸易产生，向电商公司提供公钥用于加密数据，同时数据加署名校验。流程如下：

4.3 接口报文
4.3.1 报文规则和系统限定
n 报文采用标准XML格式，字符集编码为UTF-8 。
n 报文内部各标签顺序固定按接口报文设计所示，标签无内容可留空，但不允许删除标签。
4.3.2 接口请求测试地址URL
n :9092/BIService/service/order/pushOrder
4.3.3 订单信息格式
<?xml version="1.0" encoding="utf-8"?>
<Order>
<OrderHead>
<ecCode>电商代码（检）</ecCode>
<cbeCode>电商代码（关）</cbeCode>
<ecName>电商名称（检）</ecName>
<cbeName>电商名称（关）</cbeName>
<ecpCodeCiq>电商平台代码（检）</ecpCodeCiq>
<ecpCodeCus>电商平台代码（关）</ecpCodeCus>
<ecpNameCiq>电商平台名称（检）</ecpNameCiq>
<ecpNameCus>电商平台名称（关）</ecpNameCus>
<orderNo>订单编号</orderNo>
<charge>总费用</charge>
<goodsValue>货值</goodsValue>
<freight>运费</freight>
<other>其他费用</other>
<tax>进口行邮税</tax>
<customer>客户姓名</customer>
<shipper>发货人名称</shipper>
<shipperAddress>发货人地址</shipperAddress>
<shipperTelephone>发货人电话</shipperTelephone>
<shipperCountryCiq>发货人所在国（检）</shipperCountryCiq>
<shipperCountryCus>发货人所在国（关）</shipperCountryCus>
<consignee>收货人名称</consignee>
<consigneeProvince>收货人省份</consigneeProvince>
<consigneeCity>收货人城市</consigneeCity>
<consigneeZone>收货人区县</consigneeZone>
<consigneeAddress>收货人地址</consigneeAddress>
<consigneeTelephone>收货人电话</consigneeTelephone>
<consigneeCountryCiq>收获人所在国（检）</consigneeCountryCiq>
<consigneeCountryCus>收获人所在国（关）</consigneeCountryCus>
<idType>证件类型</idType>
<idNumber>证件号码</idNumber>
<ieType>进出口标志</ieType>
<stockFlag>集货/备货</stockFlag>
<batchNumbers>批次号</batchNumbers>
<totalLogisticsNo>总运单号</totalLogisticsNo>
<tradeCountryCiq>贸易国别（检）</tradeCountryCiq>
<tradeCountryCus>贸易国别（关）</tradeCountryCus>
<agentCodeCiq>代理公司（检）</agentCodeCiq>
<agentCodeCus>代理公司（关）</agentCodeCus>
<agentNameCiq>代理公司名称（检）</agentNameCiq>
<agentNameCus>代理公司名称（关）</agentNameCus>
<packageTypeCiq>包装种类（检）</packageTypeCiq>
<packageTypeCus>包装种类（关）</packageTypeCus>
<modifyMark>操作类型</modifyMark>
<note>备注</note>
</OrderHead>
<OrderList>
<itemNoCiq>备案商品编号（检）</itemNoCiq>
<itemNoCus>备案商品编号（关）</itemNoCus>
<goodsNo>商品货号</goodsNo>
<shelfGoodsName>商品上架品名</shelfGoodsName>
<goodsName>申报品名</goodsName>
<describe>商品描述</describe>
<codeTs>HS编码</codeTs>
<ciqCode>CIQ编码</ciqCode>
<goodsModel>规格型号</goodsModel>
<taxCode>行邮税号</taxCode>
<price>成交单价</price>
<currencyCiq>币制（检）</currencyCiq>
<currencyCus>币制（关）</currencyCus>
<quantity>数量</quantity>
<priceTotal>成交总价</priceTotal>
<unitCiq>计量单位（检）</unitCiq>
<unitCus>计量单位（关）</unitCus>
<discount>折扣优惠</discount>
<giftsFlag>是否赠品</giftsFlag>
<originCountryCiq>原产国（检）</originCountryCiq>
<originCountryCus>原产国（关）</originCountryCus>
<usage>用途</usage>
<wasteMaterials>废旧物品</wasteMaterials>
<wrapTypeCiq>内件包装种类（检）</wrapTypeCiq>
<wrapTypeCus>内件包装种类（关）</wrapTypeCus>
<packNum>件数</packNum>
</OrderList>
<OrderPaymentLogistics>
<paymentCode>支付公司代码</paymentCode>
<paymentName>支付公司名称</paymentName>
<paymentType>支付类型</paymentType>
<paymentNo>支付交易号</paymentNo>
<logisticsCodeCiq>物流公司代码（检）</logisticsCodeCiq>
<logisticsCodeCus>物流公司代码（关）</logisticsCodeCus>
<logisticsNameCiq>物流公司名称（检）</logisticsNameCiq>
<logisticsNameCus>物流公司名称（关）</logisticsNameCus>
<totalLogisticsNo>总运单号</totalLogisticsNo>
<subLogisticsNo>分运单号</subLogisticsNo>
<logisticsNo>物流运单号</logisticsNo>
<trackNo>物流跟踪号</trackNo>
<trackStatus>物流跟踪状态</trackStatus>
<crossFreight>跨境运费</crossFreight>
<supportValue>保价金额</supportValue>
<weight>毛重</weight>
<netWeight>净重</netWeight>
<quantity>数量</quantity>
<deliveryWay>交货方式</deliveryWay>
<transportationWay>运送方式（检）</transportationWay>
<shipCode>运送工具（检）</shipCode>
<shipName>运送工具名称</shipName>
<destinationPort>装运港/指运港</destinationPort>
</OrderPaymentLogistics>
</Order>
4.3.4 订单信息字段说明
序号
字段名
字段英文名
类型
必填
注释
1
电商代码（检）
ecCode
a..40
是
国检备案的电商公司代码
2
电商代码（关）
cbeCode
a..40
是
海关备案的电商公司代码
3
电商名称（检）
ecName
a..100
是
国检备案的电商公司名称
4
电商名称（关）
cbeName
a..100
是
海关备案的电商公司名称
5
电商平台代码 （检）
ecpCodeCiq
a..40
是
在国检备案的电商平台代码，假如一个电商有多个电商平台，则根据订单的商品出自哪个平台，在此填写哪个电商平台代码，如电商公司在国检没有备案电商平台，以电商代码代码代替
6
电商平台代码 （关）
ecpCodeCus
a..40
是
在海关备案的电商平台代码，假如一个电商有多个电商平台，则根据订单的商品出自哪个平台，在此填写哪个电商平台代码，如电商公司在海关没有备案电商平台，以电商代码代码代替
7
电商平台名称（检）
ecpNameCiq
a..100
是
国检备案的电商平台名称
8
电商平台名称（关）
ecpNameCus
a..100
是
海关备案的电商平台名称
9
订单编号
orderNo
a..30
是
电商平台上生成的订单编号，唯一
10
总费用
charge
n..19,5
是
货值+运费+其它费用+进口行邮税=总费用，必填
11
货值
goodsValue
n..19,5
是
订单中商品的货值，即订单上所有商品总价之和
12
运费
freight
n..19,5
否
一般是指跨境的运费
13
其他费用
other
n..19,5
否
其他费用
14
进口行邮税
tax
n..19,5
否
非必填，申报时可以报关行补填
15
客户姓名
customer
a..60
否
一般是指下订单的人
16
发货人名称
shipper
a..60
是
发货人名称
17
发货人地址
shipperAddress
a..100
是
发货人地址
18
发货人电话
shipperTelephone
a..20
是
发货人电话
19
发货人所在国（检）
shipperCountryCiq
a..3
是
国检系统的发货人所在国编码（参考数据字典国检的国家代码）
20
发货人所在国（关）
shipperCountryCus
a..3
是
海关系统的发货人所在国编码（参考数据字典海关的国家代码）
21
收货人名称
consignee
a..60
是
收货人名称
22
收货人省份
consigneeProvince
a..40
是
收货人省份
23
收货人城市
consigneeCity
a..40
是
收货人城市
24
收货人区县
consigneeZone
a..40
是
收货人区县
25
收货人地址
consigneeAddress
a..100
是
收货人地址
26
收货人电话
consigneeTelephone
a..20
是
收货人电话
27
收获人所在国（检）
consigneeCountryCiq
a..3
是
国检系统的收获人所在国编码（参考数据字典国检的国家代码）
28
收获人所在国（关）
consigneeCountryCus
a..3
是
海关系统的收获人所在国编码（参考数据字典海关的国家代码）
29
证件类型
idType
a..1
进口必填，出口非必填
1-身份证 2-军官证 3-护照 4-其他
30
证件号码
idNumber
a..30
进口必填，出口非必填
根据证件类型填写相应的证件号码
31
进出口标志
ieType
a..1
是
I-进口 E-出口
32
集货/备货
stockFlag
a..1
是
1-集货 2-备货
33
批次号
batchNumbers
a..100
是
方便查询和报关行申报
34
总运单号
totalLogisticsNo
a..24
进口集货必填
运单由物流公司承运，物流公司的总运单号
35
贸易国别（检）
tradeCountryCiq
a..3
是
进口是发货人国家的国检编码，出口是收货人国家的国检编码（参考数据字典国检的国家代码）
36
贸易国别（关）
tradeCountryCus
a..3
是
进口是发货人国家的海关编码，出口是收货人国家的海关编码（参考数据字典海关的国家代码）
37
代理公司（检）
agentCodeCiq
a..40
是
一般是报关行，或者有申报权限的电商或物流公司在国检备案的公司代码（不是自己报关的必填）
38
代理公司（关）
agentCodeCus
a..40
是
一般是报关行，或者有申报权限的电商或物流公司在海关备案的公司代码（不是自己报关的必填）
39
代理公司名称（检）
agentNameCiq
a..100
是
一般是报关行，或者有申报权限的电商或物流公司在国检备案的公司名称（不是自己报关的必填）
40
代理公司名称（关）
agentNameCus
a..100
是
一般是报关行，或者有申报权限的电商或物流公司在海关备案的公司名称（不是自己报关的必填）
41
包装种类（检）
packageTypeCiq
a..4
是
包装种类（参考数据字典的国检包装种类代码）
42
包装种类（关）
packageTypeCus
a..1
是
包装种类（参考数据字典的海关包装种类代码）
43
操作类型
modifyMark
a..1
是
1-新增 2-修改 3-删除；一般为1
44
备注
note
a..1000
否
订单备注信息
45
备案商品编号（检）
itemNoCiq
a..100
否
国检备案商品编号
46
备案商品编号（关）
itemNoCus
a..100
否
海关备案商品编号
47
商品货号
goodsNo
a..20
是
电商平台上的商品货号
48
商品上架品名
shelfGoodsName
a..250
是
电商平台商品的名称
49
申报品名
goodsName
a..250
否
非必填，若不填，系统从上架品名反填
50
商品描述
describe
a..250
否
商品描述
51
HS编码
codeTs
a..14
否
商品的HS编码,即：商品名称及编码协调制度的国际公约（参考数据字典的hs编码）
52
CIQ编码
ciqCode
a..60
否
商品的CIQ编码（参考数据字典的ciq编码）
53
规格型号
goodsModel
a..250
否
规格型号
54
行邮税号
taxCode
a..8
否
商品的行邮税，按照这个进行收税
55
成交单价
price
n..19,5
否
商品成交的单价
56
币制（检）
currencyCiq
a..4
是
国检币制（参考数据字典的国检币制代码）
57
币制（关）
currencyCus
a..3
是
海关币制（参考数据字典的海关币制代码）
58
数量
quantity
n..9
是
商品成交数量
59
成交总价
priceTotal
n..19,5
是
商品的成交单价X数量
60
计量单位（检）
unitCiq
a..10
是
国检计量单位（参考数据字典的国检计量单位代码）
61
计量单位（关）
unitCus
a..10
是
海关计量单位（参考数据字典的海关计量单位代码）
62
折扣优惠
discount
n..9,2
否
商品的折扣优惠，折扣优惠不会参与计算入商品总价里面
63
是否赠品
giftsFlag
a..1
否
N-不是 Y-是（赠品单价应当为0）
64
原产国（检）
originCountryCiq
a..3
是
商品产地所在国（参考数据字典的国检国家代码）
65
原产国（关）
originCountryCus
a..3
是
商品产地所在国（参考数据字典的海关国家代码）
66
用途
usage
a..10
否
1-种用或繁殖 2- 食用 3- 奶用 4- 欣赏或演艺 5-伴侣 6-实验 7-药用 8-饲用 9-其他 10-介质土 A-食品包装材料 B-食品加工设备 C-食品添加剂 D-食品容器 E-食品洗涤剂 F-食品消毒剂
67
废旧物品
wasteMaterials
a..10
是
1-正常 2-废品 5-旧品 9-其他
68
内件包装种类（检）
wrapTypeCiq
a..4
否
参考国检包装种类代码
69
内件包装种类（关）
wrapTypeCus
a..1
否
参考海关包装种类代码
70
件数
packNum
n..9
否
件数与成交数量可以不一致，该件数指的是包装商品包装的件数
71
支付公司代码
paymentCode
a..10
是
海关备案的支付公司代码
72
支付公司名称
paymentName
a..100
是
海关备案的支付公司类型
73
支付类型
paymentType
a..1
否
A-全款S-商户款,X-行邮税
74
支付交易号
paymentNo
a..40
是
订单支付产生的支付交易号
75
物流公司代码（检）
logisticsCodeCiq
a..10
是
海关备案的物流公司代码
76
物流公司代码（关）
logisticsCodeCus
a..10
是
海关备案的物流公司代码
77
物流公司名称（检）
logisticsNameCiq
a..100
是
海关备案的物流公司名称
78
物流公司名称（关）
logisticsNameCus
a..100
是
海关备案的物流公司名称
79
分运单号
subLogisticsNo
a..24
否
当时是为了区分这三层运单的情形(即有总运单、分运单、面单)，实际中一般只有总运单和运单，是两层结构。所以物流商一般只需指定总运单号和运单号即可。
80
物流运单号
logisticsNo
a..20
否
物流运单号
81
物流跟踪号
trackingNo
a..20
否
一般是航班号，是描述字段。
82
物流跟踪状态
trackStatus
a..1
否
是物流跟踪号的状态描述，也是描述字段。不参与E贸易流程。初始化后不会再变。有4个：A-承运,R-运抵,S-签收,C-取消
83
跨境运费
crossFreight
n..19,5
否
境外运送的费用
84
保价金额
supportValue
n..19,5
否
针对一个运单里的所有商品的报价金额
85
毛重
weight
n..19,5
是
整个包裹的重量,单位（kg）
86
净重
netWeight
n..19,5
否
商品的重量，除掉包装箱的重量,单位（kg）
87
数量
quantity
n..19,5
否
一个运单就是一个包裹，不存在多个包裹。是商品数。
88
交货方式
deliveryWay
a..60
出口必填，进口非必填
通关标准的交货方式术语（参考数据字典交货方式代码）
89
运送方式（检）
transportationWay
a..2
是
国检运送方式（参考数据字典运送方式代码）
90
运送工具（检）
shipCode
a..2
是
国检运送工具（参考数据字典运送工具代码）
91
运送工具名称
shipName
a..100
否
非必填，一般填公路运送、铁路运送的多。
92
装运港/指运港
destinationPort
a..4
出口必填,进口非必填
出口指定指运港，进口指定国外的装运港（参考数据字典的装运港和指运港代码）

4.3.5 报文结构示例
n 请求报文格式：

<?xml version="1.0" encoding="UTF-8"?>
<Root>
<PubInfo>
<Version>接口版本</Version>
<CompanyCode>公司编号</CompanyCode>
<Key>公司Key</Key>
<MsgType>报文类型</MsgType>
<OptType>操作类型</OptType>
<SignaTure>数字署名</ SignaTure>
<CreateTime>创建日期</CreateTime>
</PubInfo>
<DataInfo>加密报文</DataInfo>
</Root>

n 响应报文格式：

<?xml version="1.0" encoding="UTF-8"?>
<Root>
<MsgType>报文类型</MsgType>
<CompanyCode>公司编号</CompanyCode>
<OptType>操作类型</OptType>
<BillNo>交易编号</ BillNo>
<Status>回执状态</Status>
<Detail>回执详情</Detail>
</Root>

4.3.6 请求报文字段说明
编号
字段名称
字段英文名称
字段类型及长度
必填
备注
1
接口版本
Version
a..4
是
Webservice接口版本
2
公司编号
CompanyCode
a..10
是
发送公司编号
3
公司Key
Key
a..100
是
发送公司Key；用于身份辨认
4
报文类型
MsgType
a..1
是
O-订单；W-运单
5
操作类型
OptType
a..1
是
1-新增；2-修改
6
数字署名
Signature
a..200
是
验证加密报文是否一致
7
创建日期
CreatTime
a..100
是
单据生成日期
8
加密报文
DataInfo
a..2023
是
支付信息加密后内容

4.3.7 回执报文字段说明
编号
字段名称
字段英文名称
字段类型及长度
是否必填
说明
1.
报文类型
MsgType
a..1
是
O-订单；W-运单
2.
公司代码
CompanyCode
a..10
是
发送公司编号
3.
操作类型
OptType
a..1
是
1-新增；2-修改
4.
单据编号
BillNo
a..40
否
订单回执是订单号，运单回执是运单号，支付回执是支付交易号
5.
解决结果状态
status
a..2
是
0- 入库成功；
1- 非XML报文；
2- 非授权访问；
3- 授权过期；
4- 解密失败；
5- 解密报文非xml；
6- 解密报文xml节点缺失；
7- 解密报文，节点校验失败；
8- 单据已存在；

6.
具体解决结果
detail
a..1000
否

4.3.8 数据加密说明
n 对外接口中加密报文字段是整个订单信息进行RSA加密后的内容，公钥由E贸易提供 。
n 只接受HTTP POST方式请求，请求编码格式：“application/x-www-form-urlencoded; charset=UTF-8”。
n 为保证数据完整性，报文接口中对订单信息进行署名，即：订单信息（原始xml）然后MD5；转换为Base64字符串并进行URL编码（UTF-8字符集）
n 为进一步加强接口安全性，增长”CompanyCode”和“Key”字段，用于身份辨认，“CompanyCode”和“Key”由E贸易提供。
n HTTP请求最终发送的数据样式为：
xml=<?xml version="1.0" encoding="UTF-8"?><Root><PubInfo> <Version>1.0</Version><CompanyCode>310001</CompanyCode><Key>dsiuoiosjk</Key><MsgType>O</MsgType><OptType>2</OptType><Signature>Pag0sSMMcqwYPx9LaIqmujAx6OYrR5o2mYLC4LlEUSTi+mvlG/YXSRIW+oVOi4fIS3Hh9IgDpXIp99l/PKayPmCx/DPpX4B+zR7aiKmwxA8Z1wPj1YWOTUpz2WRQzrIAqc7uCAngVbTHFqdunOfcZFNn7f28EDmBDrykcJk=</Signature><CreatTime>2023-02-21 12:12:56</CreatTime></PubInfo><DataInfo> 5p+v6JOd57u1576K5rK55peg6Imy5ZSH6IaPIDXlhYs8L2dvb2RzTmFtZT4NCjxnb29kc01vZGVsPjwvZ29vZHNNb2RlbD4NCjx0YXhDb2RlPjwvdGF4Q29kZT4NCjxwcmljZT4zOC4wMDA8L3ByaWNlPg0KPGN1cnJlbmN5PjE0MjwvY3VycmVuY3k+DQo8cXVhbnRpdHk+MTwvcXVhbnRpdHk+DQo8cHJpY2VUb3RhbD4zOC4wMDA8L3ByaWNlVG90YWw+DQo8dW5pdD4wMTI8L3VuaXQ+DQo8ZGlzY291bnQ+MC4wMDA8L2Rpc2NvdW50Pg0KPGZsYWc+TjwvZmxhZz4NCjxjb3VudHJ5PjYwMTwvY291bnRyeT4NCjxwdXJwb3NlQ29kZT48L3B1cnBvc2VDb2RlPg0KPHdhc3RlTWF0ZXJpYWxzPjE8L3dhc3RlTWF0ZXJpYWxzPg0KPHdyYXBUeXBlPjI8L3dyYXBUeXBlPg0KPHBhY2tOdW0+MTwvcGFja051bT4NCjwvT3JkZXJMaXN0Pg0KPE9yZGVyUGF5bWVudExvZ2lzdGljcz48cGF5bWVudENvZGU+PC9wYXltZW50Q29kZT4NCjxwYXltZW50TmFtZT48L3BheW1lbnROYW1lPg0KPHBheW1lbnRUeXBlPjwvcGF5bWVudFR5cGU+DQo8cGF5bWVudE5vPjwvcGF5bWVudE5vPg0KPGxvZ2lzdGljc0NvZGU+TDAwMDQ8L2xvZ2lzdGljc0NvZGU+DQo8bG9naXN0aWNzTmFtZT7msrPljZfkuK3pgJrlv6vpgJLmnI3liqHmnInpmZDlhazlj7g8L2xvZ2lzdGljc05hbWU+DQo8bG9naXN0aWNzTm8+PC9sb2dpc3RpY3NObz4NCjx0cmFja05vPjwvdHJhY2tObz4NCjwvT3JkZXJQYXltZW50TG9naXN0aWNzPg0KPC9PcmRlcj4NCg==</DataInfo></Root>

附：测试DEMO请参考附件中JAVA程序。