文档变更记录
版本 | 变更内容 | 备注 | 操作人 | 变更时间 |
V3.2 | 新增数据获取 | | Sw | 20200515 |
V3.3 | 船名，航次，提单号改为非必填字段 | | Stella | 20200608 |
V3.4 | 货代上传人、货代邮件，货代QQ | | sw | 20200805 |
appId
说明：
首先从数据输入的1：ERP服务上传文件到XHQ（信号旗）服务，信号旗服务进行处理；
有两种对接模式：
模式1：通过信号旗报关行进行报关的，我们将同步数据输出的1,2,3,4;
模式2：非信号旗报关行进行报关，我们将同步数据输出的1,2;后面需要ERP将数据输入的2,3;
一、数据输入（ERP>>XHQ）
1.文件上传接口
| 接口地址 | 测试URL：http://api.t.baoguan001.com/api/docking/upload 正式URL：http://api.platform.codeflagai.com/api/docking/upload |
| 请求方式 | post |
| 入参（JSON） | 字段 | 类型 | 描述 | 必填 | 备注 |
|---|
appId | String | 权限令牌 | Y | 身份标记(分为测试环境与线上环境) | bghId | String | 报关行ID | Y | 通过接口获取（6 通过货代appId获取报关行列表） | fileUrl | String | 网络下载地址 | Y | http://allseeing-rar.oss-cn-shanghai.aliyuncs.com/A1908010846 5575164/1564620414.zip 海运报关业务支持：zip，rar格式； | orderOutNo | String | 外部订单号 | Y | 业务编号 | isReload | String | 重传标记 | Y | “2” 表示重传，其他暂无意义 | parameter | json | 其他参数 | Y | 字段 | 类型 | 描述 | 必填 | 备注 |
|---|
| sourceAppId | String | 来源appId | N | 第三方 | | phone | String | 手机号 | N | 信号旗货代平台如果存在该手机号，为默认为上传人 | | customerName | String | 客户上传人 | N | 默认为空，标记第三方上传人 | | hdEmail | String | 货代邮箱 | N | 如果存在，则显示，不存在，则通过手机查询平台结果（20200805新增） | hdqq | String | 货代QQ | N | 如果存在，则显示，不存在，则通过手机查询平台结果（20200805新增） | declarationPort | String | 申报口岸 | N | 海关编码 | IEPort | String | 出境关别 | N | 洋山：“2248” 外港：“2225” | entyPort | String | 离境口岸 | N | 海关编码 | trafName | String | 船名 | N | | voyageNo | String | 航次 | N | | billNo | String | 提运单号 | N | | packNo | String | 件数 | N | | grossWet | String | 毛重 | N | | tradeArea | String | 贸易国 | N | 海关编码 | originalCountry | String | 运抵国 | N | 海关编码 | distinatePort | String | 指运港 | N | 海关编码 | trafModeName | String | 运输方式 | N | | declareNo | String | 报关ID | N | 业务编号预留字段 | volume | String | 体积 | N | | receiptUserName | String | 客户名称 | N | 页面显示 | noticeBgh | boolean | 等通知报关 | N | true=是 （等通知报关） false=否 （直接可报关） 接口上传默认false | paperType | boolean | 有纸报关/通关无纸化 | N | true=是 false=否 接口上传默认false | linkage | String | 多式联运 | N | twoPortLinkage=两港联动 dushanPort=独山港 Other=其他内支河 | hdUserName | String | 货代联系人 | N | 页面显示 | containerNo | String | 集箱号 | N | | hdRemark | String | 货代备注 | N | | source | String | 来源 | N | 用于页面显示 | manuscriptCheck | boolean | 校验单标识 | N | true=是 false=否 是否需要进行预录单校验 | needSecondCheck | boolean | 二审标识 | N | true=是 false=否 接口上传默认false | priorityGrade | boolean | 优先审核标识 | N | true=是 false=否 接口上传默认false | importantCheck | boolean | 重点审核标识 | N | true=是 false=否 接口上传默认false | orderCommissionCheck | boolean | 电子委托标记 | N | true=是 false=否 报关委托书为电子委托或非电子委托 | declareTime | String | 要求报关日期 | Y | yyyy-MM-dd HH：mm：ss | mergeType | String | 拼箱标识 | N | 1=出口拼箱 2=出口整箱 3=进口拼箱 4=进口整箱 5=进口分拨 6=出口自拼箱 7=进口报关 8=出口报关 | decContainersJsonArray | List | 集装箱箱号 | N | 格式： containerMd | json | 规格 | code，value | goodsNo | json | 商品项号关系 | code，value | containerId | json | 集装箱号 | code，value | lclFlag | json | 拼箱标志 | code，value | containerWt | json | 自重 | code，value |
示例：
[{ "containerMd":{"code":"","value":""}, "goodsNo":{"code":"","value":""}, "containerId":{"code":"","value":""}, "lclFlag":{"code":"","value":""}, "containerWt":{"code":"","value":""} }] 
|
|
|
| 出参（Object） | 字段 | 类型 | 描述 | 备注 |
|---|
code | int | 200=成功 | | msg | String | 接口返回信息 | | data | json | 返回数据： orderOutNo（外部流水号）
| 信号旗内部流水号 |
|
| 描述 | 上传成功以后，返回orderOutNo
|
2.单一放行数据接口
3.海关回执接口
4.上传拼箱关系接口 (已废弃)
接口地址 | 调试url：http://api.t.baoguan001.com/api/docking/lcl
正式url：http://api.platform.codeflagai.com/api/docking/lcl
|
请求方式 | post |
入参（json） | 字段
| 类型
| 描述
| 必填
| 备注
|
|---|
outNo
| String
| 拼箱号
| Y
| 唯一标记
| billNo
| String
| 主提单号
| N
| | shipName
| String
| 船名
| Y
| | voyage
| String
| 航次
| Y
| | iEPort
| String
| 出境关别
| Y
| 洋山：“2248”
外港：“2225”
| distinatePort
| String
| 指运港
| N
| | containerId
| String
| 集装箱号
| Y
| | containerMd
| String
| 集装箱规格
| Y
| | packNo
| String
| 件数
| Y
| | grossWet
| String
| 毛重
| Y
| | clcList
| json
| 拼箱订单列表
| Y
| | clcList.orderOutNo
| String
| 业务订单号
| | | clcList.billNo
| String
| 提运单号
| | |
|
出参 | 字段
| 类型
| 描述
| 备注
| code
| int
| 200=成功
| | msg
| String
| 接口返回信息
| | data
| json
| 返回数据
| |
|
| 描述 | |
5.上传拼箱任务给报关行
入参：
必填：业务编号、船名、航次、出境关别、提单号、件数、毛重(kg)、
选填：指运港、集装箱号、集装箱规格、随附文档
接口：
| 接口地址 | 调试url：http://api.t.baoguan001.com/api/docking/lcl_task 正式url：http://api.platform.codeflagai.com/api/docking/lcl_task |
| 请求方式 | post |
| 入参（DataForm） | 字段 | 类型 | 描述 | 必填 | 备注 |
|---|
appId | String | 权限令牌 | Y | 身份标记 | fileUrl | String | 随附文档 | N | 图片地址 (图片地址和订单列表必填一个，不能两者都为空) | taskId | String | 拼箱任务ID | N | 新增成功后返回的ID，修改时必填 | bghId | String | 报关行ID | Y | | outNo | String | 拼箱号 | N | | billNo | String | 提单号 | Y | | shipName | String | 船名 | Y | | voyage | String | 航次 | Y | | iEPort | String | 出境关别 | N | 外港海关，洋山港区，吴淞 | iEPortCode | String | 出境关别代码 | N | 2225-外港海关 2248-洋山港区 2202-吴淞 | declarationPort | String | 申报地海关 | N | 航交办，洋山市内 | declarationPortCode | String | 申报地海关代码 | N | 2229-航交办 2231-洋山市内 | entyPort | String | 离境口岸 | N | 外高桥，洋山港 | entyPortCode | String | 离境口岸代码 | N | 310701-外高桥 311002-洋山港 | distinatePort | String | 指运港 | N | | distinatePortCode | String | 指运港代码 | N | | containerId | String | 集装箱号 | N | | containerMd | String | 集装箱规格 | N | 20GP，40GP ，40HQ，45GP，45HQ | containerWt | String | 集装箱自重 | N | | containerMdCode | String | 集装箱规格代码 | N | 11-20GP
21-40GP
21-40HQ
21-45GP
21-45HQ | packNo | String | 件数 | N | | grossWet | String | 毛重 | N | | orders | List | 订单列表 | N | | 字段 | 类型 | 描述 | 必填 |
|---|
| String | orderOutNo | 业务编号 | Y | | String | newBillNo | 新提单号 | N |
|
|
| 出参 | 字段 | 类型 | 描述 | 备注 |
|---|
code | int | 200=成功 | | msg | String | 接口返回信息 | | data | JSON | | |
|
| 描述 | |
6 通过货代appId获取报关行列表
管理员配置好，报关行合作伙伴后，即可产生报关行列表。货代系统可以直接调用此货代对于的报关行列表
接口：
二、数据输出（XHQ >> ERP）
在后台配置回调接口地址,需求对方提供;
1.同步单证状态
| 接口地址 | 在信号旗中配置回调接口，接口地址回调方提供。 |
| 请求方式 | post |
| 入参（json） | 字段 | 类型 | 必填 | 描述 |
|---|
action | String | Y | syn_status (同步状态) | orderOutNo | String | Y | 业务流水号 | code | int | Y | 参见《附件4：信号旗订单状态》 | msg | String | Y | |
|
| 出参 | 字段 | 类型 | 必填 | 描述 |
|---|
state | boolean | Y | 成功：true 失败：false | msg | String | N | |
|
| 描述 | |
2.推送数据接口
| 接口地址 | 在信号旗中配置回调接口，接口地址回调方提供。 |
| 请求方式 | post |
| 入参（json） | 字段 | 类型 | 必填 | 描述 |
|---|
action | String | Y | send_data (制单完成数据) sendBgh_data (报关行发送数据) single_data (单一放行数据) | orderOutNo | String | Y | 业务流水号 | dataJson | json | N | 详见附件1：《单一标准数据》 |
|
| 出参 | 字段 | 类型 | 必填 | 描述 |
|---|
state | boolean | Y | 成功：true 失败：false | msg | String | N | |
|
| 描述 | |
3.海关回执接口
| 接口地址 | 在信号旗中配置回调接口，接口地址回调方提供。 |
| 请求方式 | post |
| 入参（json） | 字段 | 类型 | 必填 | 描述 |
|---|
action | String | Y | single_receipt(海关回执) | orderOutNo | String | N | 业务流水号 | billNo | String | N | 提运单号 | paramJson | json | Y | 回执json 字段 | 类型 | 必填 | 描述 |
|---|
channel | String | | 参见《附件3：海关状态》 | note | String | | 海关描述 | noticeDate | String | | 海关时间 | customMaster | String | | 主管海关 | entryId | String | | 海关编码 | releaseNotice | String | | 放行通知书文件地址 | customsDeclaration | String | | 报关单文件地址 |
|
|
| 出参 | 字段 | 类型 | 必填 | 描述 |
|---|
state | boolean | Y | 成功：true 失败：false | msg | String | N | |
|
| 描述 | |
4.订单消息通知
接口地址 | 在信号旗中配置回调接口，接口地址回调方提供。
|
请求方式 | post |
入参（json） | 字段
| 类型
| 必填
| 描述
|
|---|
action
| String
| Y
| msg_notice(订单消息通知)
| orderOutNo
| String
| Y
| 业务流水号
| code
| int
| N
| 消息状态码
| msg
| String
| Y
| 通知消息
|
|
出参 | 字段
| 类型
| 必填
| 描述
|
|---|
state
| boolean
| Y
| 成功：true
失败：false
| msg
| String
| N
| |
|
描述 | |
三、数据获取（XHQ >> ERP）
1.获取海关回执数据（所有的历史状态记录）
描述：如果对方服务在重启或者长时间未获取到，可以通过该接口来查询数据；数据有效期90天；
| 接口地址 | 调试url：http://api.t.baoguan001.com/api/docking/actionDataRow 正式url：http://api.platform.codeflagai.com/api/docking/actionDataRow |
| 请求方式 | post |
| 入参（json） | 字段 | 类型 | 必填 | 描述 |
|---|
action | String | Y | single_receipt(海关回执) | appId | String | Y | | orderOutNo | String | Y | 业务流水号 |
|
| 出参 | 字段 | 类型 | 必填 | 描述 |
|---|
code | int | 200=成功 | | orderOutNo | String | Y | 外部流水号 | msg | String | N | | data | | | | data.rows | String | 根据action查询返回相应的数据集合 | 返回字符串，如果是明文，字符串里面是一个集合； |
|
| 描述 | |
四. IM推送消息 (ERP->报关行)
ERP发送消息，给报关行的客户。直接发送到报关的想要的聊天记录中，并提供消息即使提醒
1.推送消息
接口：
| 接口地址 | 调试url：http://api.t.baoguan001.com/api/docking/sendMsg 正式url：http://api.platform.codeflagai.com/api/docking/sendMsg |
| 请求方式 | post |
| 入参（DataForm） | 字段 | 类型 | 描述 | 必填 | 备注 |
|---|
appId | String | 权限令牌 | Y | 身份标记 | msg | String | 消息内容 | Y | 《消息体》 | | sessionType | String | 会话类型 | Y | 默认是：20 | messageType | String | 消息类型 | Y | 《消息类型》 | | orderOutNo | String | 业务编号 | Y | 订单的身份 |
|
| 出参 | 字段 | 类型 | 描述 | 备注 |
|---|
code | int | 200=成功 | | msg | String | 接口返回信息 | | data | Object | | |
|
| 描述 | 示例： | 入参 | 出参 |
|---|
{
"appId":"<身份标记>",
"msg":"[{"containerId":"<集装箱号>","containerMd":"<箱规格>","containerWt":"<箱自重>","containerMdCode":"<箱规格代码>","containerSid":"<箱封号>","lclFlag":<拼箱标识>,"goodsNo":"<商品项号关系>"}]",
"sessionType":"20",
"messageType":"1706",
"orderOutNo":"<订单的身份>"
} | {
"code":200,
"msg":null,
"data":true
} |
|
附件
附件1：导入单一标准数据格式
文件
http://single-xml.oss-cn-shanghai.aliyuncs.com/doc/doc/datajson.json
说明:
http://single-xml.oss-cn-shanghai.aliyuncs.com/doc/doc/%E8%AF%A6%E7%BB%86%E6%95%B0%E6%8D%AE%E6%A0%BC%E5%BC%8F_1.pdf
附件2：回调接口类型
syn_status (同步状态)
send_data (制单数据)
sendBgh_data (报关行发送数据)
single_data(单一放行数据)
single_receipt(海关回执)
msg_notice (订单消息通知)
附件3：海关状态
| 海关状态描述 |
|---|
7=申报成功 a=签证 A=海关放行前删除或者异常处理（手工申报通知） B=担保放行 C=出口查验通知 D=海关删单 E=海关退单/不受理回执 F=放行交单 G=报关单已审结 H=海关挂起，需手工申报 I=海关无纸放行通知（放行） J=通关无纸化审结回执（审结回执一种） K=通关无纸化担保放行 L=海关已接收 M=报关单重审 N=重传文件 O=准予进卡 P=海关已放行 R=已结关 S=施检 T=需交税费 W=海关无纸验放通知（审结） X=海关准予进港回执（上海洋山保税港区专用） Y=申报失败 Z=退回修改 |
附件4：信号旗订单状态
| 信号旗订单状态 |
|---|
10=AI处理中 40=制单中 43=待操作 45=操作中 50=已撤回 61=待校验稿审核 62=校验稿审核中 63=待导入 （制单完成） 70=发单保存 80=发单中 81=申报成功 82=发单失败 90=预约申报中 100=预约申报失败 110=申报中 120=申报失败 |
