闲鱼合作方-服务端接入文档#

1. 环境准备-聚石塔接入#

由于集团安全规则，需接入聚石塔后进行调用，用户id、订单信息等必须存储在聚石塔内的数据库中，因此需要将服务端的服务均部署在聚石塔内。

相关文档：聚石塔-入塔指南

聚石塔外是可以访问塔内。聚石塔内如果需要访问塔外，需要走审批。 参考文档： 奇门自定义API场景接入流程

2. 用户登录授权#

授权登录是采⽤淘宝开放平台auth2.0⽅式进⾏的，前端的主要⼯作是获取授权码（code），由服务器端通过code 和应用密钥（AppSecret）调用taobao.top.auth.token.create这个top接口换取accessToken、token的过期时间和⽤户uid等信息。该accessToken可以用来后续请求TOP接口。

目前新接入的小程序，可以直接使用客户端API用户授权，直接获取授权码（code），不需要跳转到回调地址。

注意：授权码（code）仅能使⽤⼀次，如果已经使⽤则需要重新获取。

另外，在accessToken过期之前，不需要重新获取授权码。因此在第一次登录授权后，小程序可以生成自己的cookie，缓存在客户端内（闲鱼提供了setStorage和getStorage两个API）。避免同一用户每次进入小程序都重新获取code，否则可能会被限流。

整体流程如下：

注意： 1.授权码（code）仅能使⽤⼀次，如果已经使⽤则需要重新获取。

【接口】：taobao.top.auth.token.create

【入参】：

3. 线上服务商API及消息#

3.1 API汇总#

3.2 消息汇总#

3.3 API调用身份说明#

目前订单创建和用户基础信息接口，需要使用当前登录小程序用户（一般为买家）的accessToken进行调用。

其他订单相关发货、关闭、退款等接口库，需要使用订单的卖家的accessToken进行调用。

卖家的accessToken的获取方式：可以使用卖家的闲鱼账号登录小程序，同样在授权登录后拿到accessToken。

3.4 TOPAPI 环境地址确认#

目前使用线上环境即可。只有在闲鱼侧更新或者新增TOPAPI时，才需要配置成预发环境。

大部分场景下闲鱼也需要进行开发，一般会先在闲鱼的预发环境进行联调。预发联调的方式：

访问对外https协议地址：https://pre-gw.api.taobao.com/top/router/rest 即可，其他调用方式不变。

联调前需要联系闲鱼开发同学开通预发环境联调权限。需要提供需要联调的TOP API列表。

注：消息不支持预发联调，只能发布到线上后进行验证。

3.5 权限申请#

梳理需要用到的TOPAPI，在可以在闲鱼三方开发平台上（应用管理->申请权限）发起申请。

注意：只能申请确定需要使用到的API，如不确定可以提前与闲鱼开发同学确认。

4. 部分API详细说明#

4.1 订单创建#

服务商可以通过TOP接口调用创单API创建闲鱼订单，协议如下：

【接口】：alibaba.idle.isv.goosefish.order.create

【入参】：

【示例】：

{
      "x_global_biz_code": "jd|isvNoItemJD|twjd", // 订单业务标识
      "item_id": 123233,  // 商品id
      "amount": 1990, // 商品单价，单位分
      "virtual_item_order": false,
      "deliver_id": "112123"
    }

注：

• x_global_biz_code 为业务产品标识，由闲鱼开发同学提供
• extra_data 为订单附加信息，需要根据需求场景与闲鱼开发确认对接具体方案。
• deliver_id 和x_global_biz_code是关联的，只有在需要实物发货（需要物流）的场景才需要传入。
• deliver_id 获取方式： 见前端接入文档中的收货列表API 《闲鱼合作方-前端接入文档》

出参：

{
        "data": {
          "biz_order_id": "3318740388015865620",//订单唯一订单号
        },
        "api_success": true
    }

注：

• biz_order_id 可以作为入参调用前端支付API Goosefish.tradePay 进行订单支付。

如何判断订单是否支付成功？

• 调用前端支付API Goosefish.tradePay 时，会返回支持是否成功的结果。
• 服务端可以再次调用订单查询接口（alibaba.idle.isv.order.query）验证订单是否已支付，如果返回结果的 order_status 更新成2，代表订单已付款完成。
• 订单支付成功后，会发送订单状态变更消息。注意：消息可能会有延迟。

创单错误码信息

创单接口会返回一些错误码，仅有部分可以直接透出errorMsg给用户，罗列如下：

4.2 正向订单查询#

【接口】：alibaba.idle.isv.order.query

【入参】：注意标红为必传

【出参】: module订单信息下

【示例】：

4.3 发货接口-虚拟发货#

该接口适用于无需物流发货的场景。对应创单时不需要传入deliver_id的情况。

【接口】：alibaba.idle.isv.goosefish.virtual.delivery

【入参】：

【示例】：

{
      "idle_open_isv_virtual_delivery_param":{
        "biz_order_id": 2323232323,
      }
    }

    {
      "result":{
          "data":true
      }
    }

4.4 发货接口-有物流发货#

有实物物流的发货场景，对应创单时需要传入deliver_id的情况

【接口】：alibaba.idle.isv.order.ship

【入参】：注意标红为必传

【示例】：

{
      "biz_order_id": "1212",
      "ship_mail_no": "121212"
    }

行政区划id：

城市区划编码 division_id静态字典

4.5 物流公司编码查询（lc_code）#

【接口】：alibaba.idle.logistics.companies.query

【入参】：无

【出参】：logistics_resp_result 下

使用code即可

建议：数据单读存入数据库，备份使用即可

4.6 逆向订单查询#

【接口】：alibaba.idle.isv.refund.query

【入参】：注意标红为必传

【出参】：module订单信息下

4.7 退款单处理#

【接口】：alibaba.idle.isv.order.dealrefund

【入参】：注意标红为必传

【出参】：module 下

4.8 服务商主动取消订单（未发货）#

【接口】：alibaba.idle.isv.order.close

【入参】：

【示例】：

{
      "isv_appraise_isv_order_close_dto":{
        "biz_order_id":"12131",
        "close_reason":"商品无库存"
      }
    }

4.9 正向订单变更消息#

【topic】：idle_autotrade_OrderStateSync

【触发场景】：订单状态正向推进

【消息属性】：

4.10 逆向订单变更消息#

【topic】：idle_autotrade_RefundSync

【触发场景】：订单状态逆向推进

【消息属性】：

4.11 用户基础信息（性别、头像、昵称）#

【接口】：alibaba.idle.goosefish.user.info.query

【入参】：无

【示例】：

{
        "api_success": true,
        "data": {
          "avatar": "https://img.alicdn.com/bao/uploaded/i1/O1CN015CYSFz1aRMAi1EcHQ_!!0-mtopupload.jpg",      // 没设置过可能为null
          "gender": 0,   // 没设置过可能为null
          "nick_name": "数码爱好者"
        }
      }