海关跨境电商进口统一版信息化系统平台数据实时获取接口（试行）
V1.0
目录
1.平台开放实时数据获取接口
1.1.服务说明
服务由通关管理系统通过通关服务系统调用企业应用系统的平台支付相关实时数据获取接口，由企业返回支付相关实时数据。
1.2.集成方式
http协议，method: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.线上接入
1、服务注册
企业通过在通关服务系统注册证书信息、一个或多个实时数据抓取接口地址。通关服务系统经审核通过后，根据海关业务需求调用接口进行实时抓取，企业通过线上企业返回实时数据接口返回实时数据。
2、服务变更
企业可在通关服务系统变更实时数据抓取接口地址、证书信息，通关服务系统审核通过后，重新启用该服务。
线上企业返回实时数据接口地址：
https://customs.chinaport.gov.cn/ceb2grab/grab/realTimeDataUpload
1.4.加签说明
- 将数据内容所有数据一级节点使用||分割符拼接为连续字符串，使用IC卡、Ukey、服务类密码设备进行加签，将certNo（证书编号）、signValue（加签结果）补充入请求中。
- IC卡、Ukey加签方法见附件-1 电子口岸控件说明-企业版签名接口
- 服务类密码设备加签可联系厂商进行技术支持。
加签原文样例：
initData:sessionID”:”fe2374-8fnejf97-32839218”||”payExchangeInfoHead": {data}||”payExchangeInfoList": [{data},{data}]||”serviceTime”:1533271903898
1.5.加密授权说明
外部系统调用跨境电子商务管理进口子系统的https接口确保安全调用接口,可参照附件2-上传平台实时数据样例进行开发。
1.6.功能简介
1.6.1.企业实时数据获取接口（部署在电商平台）
1.6.1.1.功能说明
| 服务定义 | platDataOpen |
|---|---|
| 功能说明 | 企业接收海关发起的支付相关实时数据获取请求 |
| 返回值 | |
| 说明 | 该接口为http形式 |
1.6.1.2.接口参数
请求头文档类型：application/x-www-form-urlencoded;charset=UTF-8
请求body：openReq={"orderNo":"ord201800002","sessionID": "fe2374-8fnejf97-32839218","serviceTime":1533271903898}
| 参数名 | 类型 | 必填 | 传入/出 | 说明 |
|---|---|---|---|---|
| orderNo | String | Y | In | 申报订单的订单编号 |
| sessionID | string | Y | In | 海关发起请求时，平台接收的会话ID。 |
| serviceTime | Long | Y | In | 调用时的系统时间 |
参数说明
{"orderNo":"ord201800002","sessionID": "fe2374-8fnejf97-32839218", "serviceTime":1533271903898}
1.6.1.3.返回说明
返回Json格式数据
| 属性 | 类型 | 说明 |
|---|---|---|
| code | String | 状态代号。10000为正常调用值。 |
| message | String | 异常信息，正常时为空值 |
| serviceTime | Long | 系统响应时间 |
参数说明
{"code":"10000","message":"","serviceTime":1533271903898}
1.6.2.企业返回实时数据接口（部署在通关服务系统）
1.6.2.1.功能说明
| 服务定义 | realTimeDataUp |
|---|---|
| 功能说明 | 企业返回海关所需获取的支付相关实时数据 |
| 返回值 | ApiResult |
| 说明 | 该接口为https形式 |
1.6.2.2.接口参数
| 参数名 | 类型 | 必填 | 传入/出 | 说明 |
|---|---|---|---|---|
| payExInfoStr | string | Y | In | 完整请求内容 |
payExInfoStr内容说明：
| 参数名 | 类型 | 必填 | 传入/出 | 说明 |
|---|---|---|---|---|
| sessionID | string | Y | In | 海关发起请求时，平台接收的会话ID。 |
| payExchangeInfoHead | String | Y | In | 支付原始数据表头 |
| payExchangeInfoList | List | Y | In | 支付原始数据表体 |
| serviceTime | Long | Y | In | 返回时的系统时间 |
| certNo | String | Y | In | 证书编号 |
| signValue | String | Y | In | 签名结果值 |
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 | String | 状态代号。10000为正常调用值。 |
| message | String | 异常信息，正常时为空值 |
| serviceTime | Long | 系统响应时间 |
参数说明
{"code":"10000","message":"","serviceTime":1533271903898}
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 | 异常信息等。 |