跨境业务接入技术文档

1. 产品介绍

1.1 业务介绍

小米有品跨境业务是有品平台其中的一种业务模式,供应商(商家)入驻有品平台以后,可以在有品售卖海外跨境类商品(包括保税仓发货、海外直邮BC、海外直邮CC),用户产生订单以后,由商家进行拆单、清关、发货等后续流程(支付单由有品平台去申报,目前跨境类商品仅支持微信和支付宝两种支付方式)。

1.2 业务流程

用户->>有品平台:1.下单
有品平台->>第三方支付平台:2.支付
第三方支付平台->>有品平台:3.支付成功
供应商-->>有品平台:4.调用拉单接口拉订单
供应商->>供应商:5.拆单
供应商-->>有品平台:6.同步拆包裹单结果
有品平台->>第三方支付平台:7.按拆单结果报支付单
第三方支付平台->有品平台:8.返回支付单报关号
有品平台->>有品平台:9.成功or失败,更新状态
供应商-->>有品平台:10.拉包裹单对应的支付报关号
供应商->第三方物流:11.生成物流单号
第三方物流->>供应商:12.返回物流单号
供应商-->>有品平台:13.同步发货单号,平台更新订单状态为已发货
第三方物流->>第三方物流:14.直邮BC模式发货出库
供应商-->>有品平台:15.通知开始清关
供应商-->>跨境接口平台:16.报关(支付单、物流单、清单)
跨境接口平台-->供应商:17.返回清关结果
供应商-->>有品平台:18.同步包裹清关结果
有品平台->>有品平台:19.清关失败退款处理
供应商->>第三方物流:20.保税仓发货出库

注意事项:

  1. 第4步,拉订单能拉到支付两小时以后的订单,两小时内允许退款和修改收货地址,支付两个小时以后,就不允许用户主动退款和修改地址了,所以供应商拉到的订单,数据不会再变化。

  2. 第9步,平台尝试多次报关,如果重试过程没有一次成功的(目前会重试多次),就认为该单报关失败,走退款逻辑处理。(此处供应商需注意,只有拉取到支付报关号的才可以发货,CC模式需要在拆单的时候报给我们,这样我们就不会再去报支付单了)

  3. 第18步,供应商同步我们包裹清关结果,如果是清关失败,我们系统会做售后退款处理,所以此处应该谨慎处理。

2. 接入指南

供应商需要对接我们的OpenAPI服务,来完成整体的拉单、报关、清关、发货等整套流程。

OpenAPI服务接入详细文档地址

3. 接口列表

下面是上述流程中所用到的所有接口列表,参考具体的文档介绍接入。

3.1. 拉订单接口

接口名:订单列表

接口注意事项:

商户只能拉到用户已经支付两小时以后的订单,支付后前两个小时。平台支持修改地址及退款操作,两个小时以后就不允许操作了,也就是商户拉到的订单信息,是不会变的了。

3.2. 同步拆单结果接口

接口名:订单拆单

接口注意事项:

a. 接口参数中的海关编号(customsName字段),要用我们平台定义的海关,详细信息请参考本文档 附录

b. outPackageId是作为供应商标识单个包裹单的唯一编码,有品平台会判断这个单号是否同步过,如果没有,就会认为供应商重新推了一个新的包裹单过来。所以同一个包裹单,这个单号不能更换,如果在测试环境接入的时候同步错了,可以联系平台技术修改数据,线上不允许犯这种错误。同一商户下,该单号需保证唯一!

c. 还有拆单金额的问题,这个是供应商需要特殊注意的,如果拆单的话,一定要计算正确,我们会校验该订单下所有包裹单的总价之和,不能超多订单金额,但没法做每个包裹单的金额校验,这里需要供应商计算正确,如遇到小数,建议向下取整,金额之和不能超过订单金额。商品金额和邮费要分开给,不要都放到一起传,按照实际的金额来,不然会有问题,报支付单会失败

d. customsMode 如果是cc模式一定要传,保税仓和bc逻辑一样,都要平台去报支付单,cc是不需要平台去报支付单的,如果选择保税仓或者bc,平台去报支付单如果失败的时候,会进行退款处理,这里一定要特别注意,按照文档的说明来,避免钱也退了,货也发出去的情况。

e. skuId参数,skuId不是必传,但pid为必传,如果skuId没有传过来,我们会去查询,找到该pid关联的skuId作为参数值去补充上(仅限pid和skuId一对一的关系,理论上只支持一对一,但系统没有限制,如果非一对一可能报错)。

3.3. 拉取支付报关号接口

接口名:拉取支付报关号

接口注意事项:

a. payDeclareNo为报支付单的报关单号

b. 无payDeclareNo的值时,需要判断status,如果status为6,就是彻底报关失败,有品平台会操作退款处理,此处需要特殊注意,如果拉报关单号,遇到该包裹单的状态变为6,就不要再进行后续的发货流程了,直接关单即可。

c. certCheckResult这个字段为我们向第三方支付平台报关时,拿用户在有品平台的实名认证信息和第三方支付平台的实名认证信息做比对,看两边的实名认证信息是否一致,但不管结果是什么,有品平台不做任何处理。

3.4. 手动重新报关接口

接口名: 手动重新报关接口

接口注意事项:

a. oid为有品订单号,outPackageIds为商家三方包裹单号

b. 若只是需要重新报关 不需要加customsName字段。拆单时推错了报关的海关关口,可以通过customsName字段修改后重新报关 (**修改关口报关需要重新拉取支付流水)

c. 同一包裹重推的次数不能超过10次,接口不支持频繁调用只适用于清关失败(支付信息不存在)需要进行重新报关的情况。

3.5. 更新清关状态接口

更新清关状态会有三个节点,开始清关、清关成功、清关失败。

接口名:更新清关状态

接口注意事项:

a. 保税仓发货时,必须要传递以上开始清关和清关成功/失败两个节点,在同步给我们的时候,我们会记录一条trace信息,用户看物流信息的时候,就可以看到这两个节点的状态了。非保税仓发货时,如果能拿到这几个节点,也建议同步给我们,拿不到的话就不用同步了。

3.6. 同步包裹单号接口

接口名:跨境包裹物流单

接口注意事项:

a. 有品对接物流查询的服务是快刀云,参考快刀云支持的快递列表

b. 发货时bizcode参数,参考有品快递列表编码

4. 上线标准

  1. 整体流程必须在测试环境对接完成,有品同学确认数据没有问题后才可上线。因海关侧没有测试环境,所以测试环境报关单号为mock数据,整体流程串起来即可,真正发货需要线上实单验证。

  2. 线上环境需要先走几单验证,确保数据没有问题,这里需要供应商联系有品平台确认数据是否正确,有品平台开发确认数据没有问题后,才可正式上架商品销售。

5. Q&A

  1. 问: 有品商品的pid和sku是不是一对一的关系?

    答: 这里做下解释,有品可能会存在多个pid对应同一个sku的情况,也会有一个pid对应一个sku*多个(这两种情况要看供应商系统是否支持,不支持的话要和有品运营同步不能这么配置),但是不支持同一个pid同时对应多个sku的情况。

  2. 问: 遇到清关发现实名认证信息不一致的情况怎么办?

    答: 有品平台目前没有让用户修改身份证信息的功能,遇到这种情况的,都是商家客服直接联系用户,要来正确的身份证信息,再次清关处理。

  3. 问: 2小时内退款的单子商家还可以拉到订单么?

    答: 用户支付2小时内申请退款的单子,订单会变成已退款的状态,商家是拉不到订单的。

  4. 问: 超过2小时的订单,用户想申请退款,是怎么一个退款流程?

    答: 目前非CC的是操作拆单->报关失败,这样我们系统会自动退款。CC模式的可以是操作拆单->虚假发货(就是推一个假的物流单号过来),然后去YMS后台代客建单,操作退款。

  5. 问: 已发货的订单,物流信息支持修改么?

    答: 目前已经同步物流单号的订单,不支持修改物流信息。

  6. 问: 商家条形码怎么和平台的pid以及sku_id关联?

    答:订单列表接口 常见问题。

  7. 更多问题 见 跨境业务相关接口相关报错处理Q&A

6. 附录

海关编号映射表:

海关名称 有品海关编号 支付宝海关编号 支付宝后推海关编号 微信海关编号 微信后推海关编号
总署 zongshu zongshu GUANGZHOU_ZS
郑州 zhengzhou zhengzhou ZHENGZHOU_BS
宁波 ningbo ningbo NINGBO
河南 henan henan zongshu
天津 tianjin tianjin TIANJIN
南沙国检 nansha_gj nanshagj
上海海关 shanghai shanghai_cbt SHANGHAI_ZS
广州海关(机场) guangzhou_airport zongshu
广州海关(南沙) guangzhou_nansha zongshu GUANGZHOU_NS_GJ GUANGZHOU_ZS
广州海关(黄埔) guangzhou_huangpu zongshu GUANGZHOU_HP_GJ GUANGZHOU_ZS
广州海关(沙田) guangzhou_shatian zongshu
杭州总署 hangzhou_zongshu zongshu HANGZHOU_ZS
广州总署 guangzhou_zongshu GUANGZHOU_ZS
重庆 chongqing CHONGQING
深圳 shenzhen SHENZHEN
郑州综合总署 zhengzhou_zh_zongshu ZHENGZHOU_ZH_ZS
©xiaomiyoupin.com 苏B2-20180351 苏ICP备18025642号-1            该文件修订时间: 2023-04-26 01:54:18

results matching ""

    No results matching ""