平台数据实时获取接口
海关跨境电商进口统一版信息化系统平台数据实时获取接口（试行）
海关总署公告2018年第179号
海关规范性文件
海关总署公告2018年第179号（关于实时获取跨境电子商务平台企业支付相关原始数据接入有关事宜的公告）
为做好海关总署2018年165号公告执行工作，现就海关实时获取跨境电子商务平台企业支付相关原始数据企业接入有关事宜公告如下：
一、支付相关原始数据的接口文档及接入方式参见《海关跨境电商进口统一版信息化系统平台数据实时获取接口（试行）》（详见附件）。有关接口如有变更将通过“互联网+海关”一体化网上办事服务平台“文档资料”栏目及时发布。
二、跨境电子商务平台使用数字签名技术向海关提供数据，并对所提数据承担法律责任。
本公告自2019年1月1日起施行。
特此公告。
附件： 海关跨境电商进口统一版信息化系统平台数据实时获取接口（试行）.zip
海关总署
2018年12月3日
1.1 服务说明
服务由通关管理系统通过通关服务系统调用企业应用系统的平台支付相关实时数据获取接口，由企业返回支付相关实时数据。
1.2 集成方式
HTTP协议，POST请求调用。
1.3 数据接入
企业通过联调环境数据上传测试后，可在线上环境进行服务注册及上线。
1.3.1 数据上传测试
企业通过调用通关服务系统接口进行测试数据上传，企业通过联调企业返回实时数据接口返回实时数据。
【联调环境】联调企业返回实时数据接口地址：
https://swapptest.singlewindow.cn/ceb2grab/grab/realTimeDataUpload
测试成功结果：
{
"code": "10000",
"message": "上传成功",
"total": 0,
"serviceTime": 1542337661665
}测试失败结果：
{
"code": "20000",
"message": "上传失败",
"total": 0,
"serviceTime": 1542338687081
}1.3.2 线上接入
服务注册
企业通过在
通关服务系统注册证书信息、一个或多个实时数据抓取接口地址。通关服务系统经审核通过后，根据海关业务需求调用接口进行实时抓取，企业通过线上企业返回实时数据接口返回实时数据。
服务变更
企业可在
通关服务系统变更实时数据抓取接口地址、证书信息，通关服务系统审核通过后，重新启用该服务。
【线上环境】线上企业返回实时数据接口地址：
https://customs.chinaport.gov.cn/ceb2grab/grab/realTimeDataUpload
1.4 加签说明
- 将数据内容所有数据
一级节点使用||分割符拼接为连续字符串，使用IC卡、UKey、服务类密码设备进行加签，将certNo（证书编号）、signValue（加签结果）补充入请求中。 - IC卡、UKey加签方法见附件-1 电子口岸控件说明-企业版签名接口
- 服务类密码设备加签可联系厂商进行技术支持。
加签原文initData样例：
"sessionID":"海关会话id"||"payExchangeInfoHead":{data}||"payExchangeInfoList":[{data},{data}]||"serviceTime":"毫秒时间戳"1.5 加密授权说明
外部系统调用跨境电子商务管理进口子系统的https接口确保安全调用接口，可参照附件2-上传平台实时数据样例进行开发。
1.6 功能简介
1.6.1 企业实时数据获取接口（部署在电商平台）
提示
海关 通关服务系统 请求调用时：
请求方法：
POSTContent-Type：
application/x-www-form-urlencodedBody参数：
openReq={"orderNo":"申报订单的订单编号","sessionID": "海关会话ID", "serviceTime":毫秒时间戳}
1.6.1.1 功能说明
| 服务定义 | platDataOpen |
|---|---|
| 功能说明 | 企业接收海关发起的支付相关实时数据获取请求 |
| 说明 | 该接口为http形式 |
1.6.1.2 接口参数
请求Body参数：
openReq={"orderNo":"申报订单的订单编号","sessionID": "海关会话ID", "serviceTime":毫秒时间戳}
{
"orderNo": "申报订单的订单编号",
"sessionID": "海关回话ID",
"serviceTime": 1533271903898
}参数说明
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| orderNo | String | Y | 申报订单的订单编号 |
| sessionID | String | Y | 海关发起请求时，平台接收的会话ID。 |
| serviceTime | Long | Y | 调用时的系统毫秒时间戳 |
1.6.1.3 返回说明
返回Json格式数据
{
"code": "10000",
"message": "",
"serviceTime": 1533271903898
}参数说明
| 属性 | 类型 | 说明 |
|---|---|---|
| code | String | 状态代号。10000为正常调用值。 |
| message | String | 异常信息，正常时为空值 |
| serviceTime | Long | 系统响应时间 |
1.6.2 企业返回实时数据接口（部署在通关服务系统）
1.6.2.1 功能说明
| 服务定义 | realTimeDataUp |
|---|---|
| 功能说明 | 企业返回海关所需获取的支付相关实时数据 |
| 返回值 | ApiResult |
| 说明 | 该接口为https形式 |
1.6.2.2 接口参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| payExInfoStr | string | Y | 完整请求内容 |
payExInfoStr 内容说明：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| sessionID | String | Y | 海关发起请求时，平台接收的会话ID。 |
| payExchangeInfoHead | Object | Y | 支付原始数据表头 |
| payExchangeInfoList | List | Y | 支付原始数据表体 |
| serviceTime | Long | Y | 返回时的系统时间 |
| certNo | String | Y | 证书编号 |
| signValue | String | Y | 签名结果值 |
支付原始数据表头 payExchangeInfoHead 结果集属性描述
| 属性 | 类型 | 说明 |
|---|---|---|
| guid | String | 系统唯一序号 |
| initalRequest | String | 原始请求 |
| initalResponse | String | 原始响应 |
| ebpCode | String | 电商平台代码 |
| payCode | String | 支付企业代码 |
| payTransactionId | String | 交易流水号 |
| totalAmount | double | 交易金额 |
| currency | String | 币制 |
| verDept | String | 验核机构 |
| payType | String | 支付类型 |
| tradingTime | String | 交易成功时间 |
| note | String | 备注 |
支付原始数据表体 payExchangeInfoList 结果集属性描述
| 属性 | 类型 | 说明 |
|---|---|---|
| orderNo | String | 订单编号 |
| goodsInfo | List | 商品信息 |
| recpAccount | String | 收款账号 |
| recpCode | String | 收款企业代码 |
| recpName | String | 收款企业名称 |
商品信息 goodsInfo 属性描述
| 属性 | 类型 | 说明 |
|---|---|---|
| gname | String | 商品名称 |
| itemLink | String | 商品展示链接地址 |
1.6.2.3 返回说明
返回Json格式数据
{
"code": "10000",
"message": "",
"serviceTime": 1533271903898
}参数说明
| 属性 | 类型 | 说明 |
|---|---|---|
| code | String | 状态代号。10000为正常调用值。 |
| message | String | 异常信息，正常时为空值 |
| serviceTime | Long | 系统响应时间 |
1.6.3 接口内容
payExchangeInfoHead 支付原始数据表头
| 中文名称 | 名称 | 类型 | 说明 | 必填 |
|---|---|---|---|---|
| 系统唯一序号 | guid | C..36 | 企业系统生成36位唯一序号（英文字母大写）。 | 是 |
| 原始请求 | initalRequest | C..8000 | 跨境电商平台企业向支付企业发送的原始信息 | 是 |
| 原始响应 | initalResponse | C..8000 | 支付企业向跨境电商平台企业反馈的原始信息 | 是 |
| 电商平台代码 | ebpCode | C..18 | 电商平台的海关注册登记编号。 | 是 |
| 支付企业代码 | payCode | C..18 | 支付企业的海关注册登记编号。 | 是 |
| 交易流水号 | payTransactionId | C..60 | 交易唯一编号（可在央行认可的机构验证） | 是 |
| 交易金额 | totalAmount | N19,5 | 实际交易金额 | 是 |
| 币制 | currency | C..4 | 实际交易币制（海关编码） | 是 |
| 验核机构 | verDept | C1 | 1-银联 2-网联 3-其他 | 是 |
| 支付类型 | payType | C1 | 用户支付的类型。1-APP 2-PC 3-扫码 4-其他 | 否 |
| 交易成功时间 | tradingTime | C..14 | 交易支付时间。 | 是 |
| 备注 | note | C..1000 | 否 |
payExchangeInfoList 支付原始数据表体
| 中文名称 | 名称 | 类型 | 说明 | 必填 |
|---|---|---|---|---|
| 订单编号 | orderNo | C..60 | 交易平台向海关申报订单的的订单编号。需返回原始请求内的所有订单。 | 是 |
| 商品信息 | goodsInfo[] | 商品名称及商品展示链接地址列表 | 是 | |
| 收款账号 | recpAccount | C..60 | 交易商品的卖方商户账号。电商平台自营商户应填写自营商户的收款账户；非自营电商应填写非自营商户的收款账户。 | 是 |
| 收款企业代码 | recpCode | C..18 | 应填写收款企业代码（境内企业为统一社会信用代码；境外企业可不填写） | 否 |
| 收款企业名称 | recpName | C..100 | 应填写收款企业名称。 | 是 |
goodsInfo 商品信息
| 中文名称 | 名称 | 类型 | 说明 | 必填 |
|---|---|---|---|---|
| 商品名称 | gname | C..250 | 商品名称应据实填报。 | 是 |
| 商品展示链接地址 | itemLink | C..3000 | 商品展示链接地址应据实填报。 | 是 |
1.6.4 异常错误码表
| code | msg |
|---|---|
| 10000 | 成功 |
| 20000 | 失败 |
| 20001~21000 | 异常信息等。 |