由于集团安全规则，需接入聚石塔后进行调用，用户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
【入参】：
字段 类型 介绍 code String 授权code，前端组件获取到的code 3. 线上服务商API及消息# 3.1 API汇总# 序号 模块 中文名 接口 1 订单 订单创建 alibaba.idle.isv.goosefish.order.create 2 订单 订单查询-正向 alibaba.idle.isv.order.query 3 订单 虚拟发货（无物流场景） alibaba.idle.isv.goosefish.virtual.delivery 4 订单 物流发货 alibaba.idle.isv.order.ship 5 订单 订单查询-逆向 alibaba.idle.isv.refund.query 6 订单 发货前关闭订单 alibaba.idle.isv.order.close 7 订单 部分退款 alibaba.idle.isv.order.part.refund 8 订单 发货后退款关单 alibaba.idle.isv.order.after.send.refund 9 订单 退货退款处理 alibaba.idle.isv.order.dealrefund 10 订单 物流公司编码查询 alibaba.idle.logistics.companies.query 11 用户 用户基础信息 alibaba.idle.goosefish.user.info.query 12 用户 用户年龄信息（是否实名认证、是否满18岁、是否满16岁）。注：实名认证认证过才有年龄信息，否则为空 alibaba.idle.isv.open.user.age.info.query 13 用户 用户是否绑定支付宝 alibaba.idle.isv.open.user.bind.account.query 3.2 消息汇总# 序号 模块 中文名 topic 1 订单 正向交易消息 idle_autotrade_OrderStateSync 2 订单 逆向交易消息 idle_autotrade_RefundSync 3.3 API调用身份说明#目前订单创建和用户基础信息接口，需要使用当前登录小程序用户（一般为买家）的accessToken进行调用。
其他订单相关发货、关闭、退款等接口库，需要使用订单的卖家的accessToken进行调用。
卖家的accessToken的获取方式：可以使用卖家的闲鱼账号登录小程序，同样在授权登录后拿到accessToken。
浏览器访问 https://open.api.goofish.com/authorize?response_type=token&client_id=${appKey}&sp=xianyu&force_auth=true 登录授权后即可拿到accessToken，有效期180天。
3.4 TOPAPI 环境地址确认# TOP预发地址 https://pre-gw.api.taobao.com/top/router/rest TOP正式地址 https://gw.api.taobao.com/router/rest目前使用线上环境即可。只有在闲鱼侧更新或者新增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
【入参】：
属性 属性名称 介绍 item_id 商品ID 服务商app发布闲置宝贝进行获取，分享宝贝发布群内，告知闲鱼技术进行查询定位到商品ID，统一使用商品ID进行拉起创单 x_global_biz_code 订单业务产品标识，与闲鱼开发确认 amount 商品单价，单位分 deliver_id 只有在需要实物发货（需要物流）的场景才需要传入 virtual_item_order 是否为虚拟商品下单 默认为false virtual_item_code 虚拟商品code virtual_item_order=true时必填 extra_data 订单附加信息 订单附加信息【示例】：
{ "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给用户，罗列如下：
errorCode errorMsg 备注 HOT_ITEM_SENTINAL_FLOW_LIMIT 人太多了，被挤爆了 HOT_ITEM_FLOW_LIMIT 人太多了，被挤爆了！ ZFB_NOT_BIND 请先绑定支付宝。 USER_NEED_VERIFY 亲, 你还未完成实人认证 NEED_XIANYU_CERTIFIED 未完成闲鱼认证 NEED_ZFB_CERTIFIED 为了你的交易安全，请前往支付宝完成实名认证 NEED_ZFB_BIND_AGREEMENT 请先签署支付宝绑定协议 ADDRESS_CHECK_AGAIN 请重新编辑地址，并保证地址信息完整 BUYER_TOO_MANY_UNPAID_ORDERS 亲，您有太多未付款订单了 AGE_18_NOT_ENOUGH 文案可能会变动，直接透出即可 HIGH_DANGER_CHECK 亲，您的闲鱼下单权限被限制，请至【我的-安全中心-违规记录】查询您的违规记录。 4.2 正向订单查询#【接口】：alibaba.idle.isv.order.query
【入参】：注意标红为必传
属性 属性名称 介绍 biz_order_id 订单号 买家下单单号【出参】: module订单信息下
属性 属性名称 介绍 biz_order_id 订单号 买家下单单号 order_status 订单状态 0：未知状态 1：订单已创建 2：订单已付款 3：已发货 4：交易成功 5：已退款 6：交易关闭 order_sub_status 订单子状态 buy_amount 商品购买数量 buyer_nick 买家昵称 不唯一且买家可以自己更改 payment 实付金额 单位分 buyer_address 买家收货地址 name 收件人姓名 phone 电话号码 prov 省份 city 城市 area 行政区 town 城镇/街道 address 详细地址 create_time 订单创建时间戳 单位毫秒 pay_time 订单下单付款时间戳 单位毫秒 post_fee 邮费 单位分 logistics 物流信息 express_no 快递单号 express_comp_name 快递公司名称 ship_time 订单发货时间戳 单位毫秒 end_time 订单完结时间戳 单位毫秒 seller_nick 卖家昵称 sku sku信息 格式： skuId|属性名:属性值;属性名:属性值 out_pay_id 支付宝订单号 encryption_buyer_id 加密的买家id encryption_seller_id 加密的卖家id service_compensate_list 服务赔付单信息列表 biz_order_id 主订单号 apply_id 赔付单申请id service_type 服务赔付单类型 NFR（描述不符包邮退） VNR（虚拟-描述不符全额退） FD_24HS（极速发货-24小时） FD_10MS（极速发货-10分钟） amount 赔付金额 单位分 status 赔付单状态 10：已创建 30：卖家已拒绝 40：人工审核中 50：卖家同意履约单结束 51：人工审核同意结束 52：人工审核拒绝履约单结束 53：买家超时未处理,自动结束 54：卖家超时未处理,自动支付 1001：处理前买家取消 1002：卖家拒绝买家取消 create_time 赔付单创建时间戳 单位毫秒 cancel_times 取消的次数 refuse_reason 卖家拒绝原因 reason_choices 卖家选择的拒绝原因 reason_desc 拒绝的描述 virtual_delivery_info 虚拟收货信息 account 虚拟收货账号 ip 买家下单ip x_global_biz_code 子业务标识【示例】：
4.3 发货接口-虚拟发货#该接口适用于无需物流发货的场景。对应创单时不需要传入deliver_id的情况。
【接口】：alibaba.idle.isv.goosefish.virtual.delivery
【入参】：
属性 属性名称 介绍 biz_order_id 订单ID【示例】：
{ "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 订单号 ship_mail_no 运单号 logistics_company 物流公司 sender_phone 发货人手机号码 用于菜鸟同步物流信息 sender_address 发货人地址 sender_name 发货人姓名 sender_divisionid 行政区划Id 最小行政单位code lc_code 快递公司编码 自行查看 3.2.4接口【示例】：
{ "biz_order_id": "1212", "ship_mail_no": "121212" }行政区划id：
城市区划编码 division_id静态字典
4.5 物流公司编码查询（lc_code）#【接口】：alibaba.idle.logistics.companies.query
【入参】：无
【出参】：logistics_resp_result 下
属性 属性名称 介绍 company_list 全部公司列表 code 快递公司代码 name 快递公司名称 id 快递公司id total 快递公司总数 hot_company_list 热门公司列表 code 快递公司代码 name 快递公司名称 id 快递公司id使用code即可
建议：数据单读存入数据库，备份使用即可
4.6 逆向订单查询#【接口】：alibaba.idle.isv.refund.query
【入参】：注意标红为必传
属性 属性名称 介绍 biz_order_id 订单号【出参】：module订单信息下
属性 属性名称 介绍 biz_order_id 订单号 买家下单单号 order_status 订单状态 0：未知状态 1：订单已创建 2：订单已付款 3：已发货 4：交易成功 5：已退款 6：交易关闭 buy_amount 商品购买数量 buyer_nick 买家昵称 不唯一且买家可以自己更改 payment 实付金额 单位分 buyer_apply_reason 买家申请退款原因 buyer_apply_sub_reason 买家退款说明 买家申请退款二级原因 goods_status 货物状态 1: 未收到货 2: 已收到货 3: 已寄回 4: 未发货 5: 卖家确认收货 6: 已发货 item 商品信息 item_id 商品Id pic_url 商品图片 price 商品价格 单位分 title 商品标题 need_return_goods 买家是否需要退货 buyer_apply_desc 买家申请退款描述 refund_create_time 退款申请时间戳 单位毫秒 refund_fee 退还金额 单位分 refund_id 退款订单号 refund_post_company 退货-快递公司名称 refund_post_no 退货-快递单号 refund_status 退款订单状态 1: 买家已经申请退款，等待卖家同意, 2: 卖家已经同意退款，等待买家退货, 3: 买家已经退货，等待卖家确认收货, 4: 退款关闭, 5: 退款成功, 6: 卖家拒绝退款, 8: 等待卖家确认退货地址, 9: 没有申请退款, 11: 退款结束 refund_modify_time 退款最新修改时间戳 单位毫秒 seller_agree_msg 卖家同意退货说明 seller_nick 卖家昵称 seller_refuse_msg 卖家拒绝退款说明 seller_refuse_reason 卖家拒绝退款原因 timeout_data 退款超时信息 create 退款超时创建时间戳 单位毫秒 modified 退款超时修改时间戳 单位毫秒 duration 退款超时时长 时间长度(毫秒) timeout 退款超时时间点时间戳 单位毫秒 timeout_status 退款超时运行状态 0:超时创建完成 1:超时运行中 2:超时暂停 3:超时关闭 4:超时失败 5:超时成功 timeout_action_type 退款超时动作类型 encryption_buyer_id 加密的买家id encryption_seller_id 加密的卖家id 4.7 退款单处理#【接口】：alibaba.idle.isv.order.dealrefund
【入参】：注意标红为必传
属性 属性名称 介绍 biz_order_id 订单号 lee_message 退款操作说明 operation 退款操作 退货退款情况下，先调用同意退货接口，收到货再调用这个接口 AGREE_REFUND-同意退款并执行打款->退款成功，仅退款情况下，直接调用； REFUSE_REFUND-拒绝退货 -> 退款关闭 AGREE_RETURN-同意退货并提供退货地址 -> 等待买家退货 场景： ①退货退款 先推AGREE_RETURN 同意退货 再推AGREE_REFUND 同意退款 ②只需退款 推REFUSE_REFUND 同意退款 return_goods_address 退货地址 address_detail 全详细地址 mobile_phone 手机号码 province 省份 city 城市 area 行政区 town 城镇/街道 consignee_name 收件人姓名 post_code 邮编 tel_no 固话【出参】：module 下
属性 属性名称 介绍 biz_order_id 订单号 dispute_id 退款单ID apply_refund_fee 申请退款金额 real_refund_fee 实际退款金额 refund_status 退款状态 1: 买家已经申请退款，等待卖家同意, 2: 卖家已经同意退款，等待买家退货, 3: 买家已经退货，等待卖家确认收货, 4: 退款关闭, 5: 退款成功, 6: 卖家拒绝退款, 8: 等待卖家确认退货地址, 9: 没有申请退款, 11: 退款结束 refund_time 退款时间 refund_type 申请退款类型 REFUND_ONLY_NO_SHIP-未发货仅退款 REFUND_ONLY_NO_RECIVE-已发货未收到货仅退款 REFUND_ONLY_WHIT_GOODS-收到货仅退款(退货退款) return_goods_status 退货状态 1: 未收到货 2: 已收到货 3: 已寄回 4: 未发货 5: 卖家确认收货 6: 已发货 timeout 到达下一个节点的超时时间点 4.8 服务商主动取消订单（未发货）#【接口】：alibaba.idle.isv.order.close
【入参】：
属性 属性名称 介绍 biz_order_id 订单id close_reason 关闭订单原因 商品无库存【示例】：
{ "isv_appraise_isv_order_close_dto":{ "biz_order_id":"12131", "close_reason":"商品无库存" } } 4.9 正向订单变更消息#【topic】：idle_autotrade_OrderStateSync
【触发场景】：订单状态正向推进
【消息属性】：
属性 类型 必须 示例值 描述 order_id Number 是 12121212121212 订单id order_status String 是 1 订单状态： 1:订单已创建/等待买家付款 2:订单已付款/等待卖家发货 3:已发货/等待买家确认收货 4:交易成功 5:已退款 6:交易关闭 order_sub_status String 否 init 订单子状态 各业务有所区别，需要与技术小二具体对接。 x_global_biz_code String 是 virtual|autoRecharge|service 交易产品业务标识 4.10 逆向订单变更消息#【topic】：idle_autotrade_RefundSync
【触发场景】：订单状态逆向推进
【消息属性】：
名称 类型 必须 示例值 描述 order_id Number 是 12345678 订单id order_status String 是 2 订单状态： 1: 买家已经申请退款，等待卖家同意, 2: 卖家已经同意退款，等待买家退货, 3: 买家已经退货，等待卖家确认收货, 4: 退款关闭, 5: 退款成功, 6: 卖家拒绝退款, 8: 等待卖家确认退货地址, 9: 没有申请退款, 11: 退款结束。 order_sub_status String 否 init 订单子状态 各业务有所区别，需要与技术小二具体对接。 x_global_biz_code String 是 jd 业务标识 4.11 用户基础信息（性别、头像、昵称）#【接口】：alibaba.idle.goosefish.user.info.query
【入参】：无
【示例】：
{ "api_success": true, "data": { "atar": "https://img.alicdn.com/bao/uploaded/i1/O1CN015CYSFz1aRMAi1EcHQ_!!0-mtopupload.jpg", // 没设置过可能为null "gender": 0, // 没设置过可能为null "nick_name": "数码爱好者" } } 4.12 用户年龄信息（是否实名认证、是否满18岁、是否满16岁）。注：实名认证认证过才有年龄信息，否则为空#【接口】：alibaba.idle.isv.open.user.age.info.query
【入参】：无
【示例】：
{ "alibaba_idle_isv_open_user_age_info_query_response": { "api_success": true, "data": { "adult16": true, "adult18": true, "certified": true }, "request_id": "10oev97ttd1s8" } } 4.13 用户是否绑定支付宝#【接口】：alibaba.idle.isv.open.user.bind.account.query
【入参】：无
【示例】：
{ "alibaba_idle_isv_open_user_bind_account_query_response": { "api_success": true, "data": { "bind_account": true }, "request_id": "772o61dk5sg5" } }