集成指南

2026-06-08 10:27

本指南介绍集成流程的各步骤，请阅读本章节了解与 WorldTrade 集成的整体过程。

集成流程分为以下几个步骤：

集成准备
集成开发
完成验收测试
发布至生产环境

集成准备

阅读集成文档

在与万里汇集成前，集成商需阅读相关文档，了解对应方案的后续集成步骤，包括：

集成指南（本文档）
API概览：了解报文传输结构，包括请求头和响应头结构等；
生成签名及加验签：了解如何对请求加签、对响应验签以及签名示例；
API列表：了解可调用的具体接口、接口调用方向和具体业务用途；
幂等字段：了解API调用时的幂等字段。

制定集成方案

集成商需联系万里汇技术支持并制定集成方案。

交换身份验证及其他信息

下表为集成商在两个不同环境（测试和生产环境）中集成需要向万里汇提供或获取的信息：

环境	向万里汇获取	向万里汇提供
测试环境	万里汇测试账户（包含买家和卖家账户）	按照生成签名及加验签文档生成的公钥
	万里汇公钥	接受通知的域名
	访问域名	调用 IP
	clientId	调用 IP
生产环境	万里汇买家账户（可选）	按照生成签名及加验签文档生成的公钥
	万里汇公钥	账号 ID
	访问域名
	clientId

表1. 集成商在测试和生产环境需要与万里汇交换的信息

集成开发

集成商可根据具体业务需求，与万里汇团队一起完成开发和集成，集成商可使用 WorldTrade 的接口实现上传文件、创建订单、发起支付、查询订单详情、订单发货等功能。WorldTrade 解决方案部分接口具有依赖关系，建议集成商按照下述步骤进行集成开发。

Oauth 授权（可选）

通过 OAuth 授权，获取调用 WorldTrade 相关 API 的访问令牌，实现业务对接。下图展示了授权管理的接口调用流程：

图1. 集成商授权管理的整体流程

订单管理及通知

下图展示了 WorldTrade 订单管理及通知接口集成的整体流程：

截屏2025-03-31 10.46.00.png

图2. 订单管理及通知接口集成的整体流程

步骤一：上传文件

调用 uploadAttachment 接口，上传相应的商品图片、发货材料证明等文件。注意 bizType 参数的使用规则：

如需后续调用 createTradeOrder 接口创建贸易订单，入参 bizType 应使用取值：WT_B2B_TRADE_PRODUCT；
如需后续调用 createDelivery 接口创建发货订单，入参 bizType 应使用以下取值之一：WT_B2B_DELIVERY_LOGISTICS、WT_B2B_DELIVERY_OTHER或WT_B2B_DELIVERY_ENTRY。

接口调用成功后，万里汇将返回相应的 fileKey 及 fileName 参数，用于创建订单、发货接口的参数传递。

注意：如需批量上传商品图片，可跳过此步骤，在步骤二中调用 createTradeOrder 接口，使用productList.imageFile.fileUrl 参数，上传包含所有商品图片的文件Url。

步骤二：创建贸易订单

集成商可调用 createTradeOrder 接口，上传贸易订单的相关详细信息，创建 WorldTrade 贸易订单。订单创建成功后，万里汇将返回订单链接及订单支付链接。

注意：
createTradeOrder 接口入参 requestId 为幂等字段，每次调用需使用不同取值。
集成商如需集成通知接口，须在 createTradeOrder 接口的三个通知地址字段（payResultNotifyUrl、orderResultNotifyUrl 及 deliveryResultNotifyUrl 字段）中填写真实有效的通知URL。

若订单不符合万里汇风控要求，万里汇将通过 notifyTradeOrderCloseResult 接口，向集成商返回订单的关闭结果。

步骤三：查询订单详情

订单创建后，集成商可调用 queryTradeOrder 接口，查看订单详情，如：订单支付阶段（首尾款/全款）、订单支付结果信息、发货信息等。

步骤四：创建发货订单

根据步骤一以及步骤二的返回结果，集成商可调用 createDelivery 接口，创建发货请求。成功创建发货请求后，万里汇将返回发货批次单号信息。

注意：createDelivery 接口入参 requestId 为幂等字段，每次调用需使用不同取值。

万里汇将通过 notifyDeliveryAuditResult 接口，向集成商返回发货审核结果。

步骤五：接收并回应结果通知

集成商在调用创建订单接口时（步骤二），通过对 payResultNotifyUrl, orderResultNotifyUrl 和 deliveryResultNotifyUrl 三个字段传送实际有效的通知地址，万里汇则会向集成商发送如下类型的通知：

notifyTradeOrderCloseResult ：仅在订单审核被拒绝时进行通知（成功不会通知）
notifyPaymentResult：仅在买家支付成功时进行通知（失败不会通知）
notifyDeliveryAuditResult：发货审核通过或拒绝时均会通知。

注意：
在接收到万里汇通知后，集成商需要对通知进行响应，以确认信息收到，具体响应头信息请参见：API 概览。
在发送响应回执时，需要对回执进行加签，具体加签步骤请参见：生成签名及加验签章节。

完成验收测试

完成验收用例（由万里汇技术人员提供），产出集成报告，集成商需联系万里汇技术支持了解验收测试详情。

发布至生产环境

应用通过验收测试后，集成商即可切换至生产环境参数，如修改clientId、密钥等，并部署到生产环境。