createTradeOrder需要签名验签

2026-02-04 06:31

POST /amsin/api/v1/business/worldtrade/createTradeOrder

集成商可调用此接口创建WorldTrade贸易订单。

报文结构

万里汇接口的报文结构包括：请求头、请求体、响应头和响应体。

请求头

入参

requestId String REQUIRED

针对本次创建订单请求，由集成商指定的唯一请求号，该字段幂等。

更多信息：

最大长度：64 字符

exchangeFlag String REQUIRED

是否需要进行结汇。可取值范围：

Y：需要结汇
N：不需要结汇

commerceScene String CONDITIONAL

贸易模式。可取值范围：

COMMON_TRADE：通用跨境电商贸易模式（9610）
GENERAL_TRADE：一般货物贸易模式（0110）

当 exchangeFlag 字段取值为 Y 时，此字段为必传。

totalAmount Amount REQUIRED

订单总金额。

计算公式为：
当订单无折扣时：totalAmount = productList.specification.totalAmount + logisticsInsuranceFee + logisticsInspectionFee + shippingFee，即订单总金额 = 商品总额 + 物流保险费 + 物流验货费 + 运费
当订单有折扣，且discountType取值为PERCENTAGE时：totalAmount = productList.specification.totalAmount * (1 - discountRate / 100) + logisticsInsuranceFee + logisticsInspectionFee + shippingFee，即订单总金额 = 商品总额 * (1 - 折扣率 /100) + 物流保险费 + 物流验货费 + 运费
当订单有折扣，且discountType取值为AMOUNT时：totalAmount = productList.specification.totalAmount - discountAmount + logisticsInsuranceFee + logisticsInspectionFee + shippingFee，即订单总金额 = 商品总额 - 折扣金额 + 物流保险费 + 物流验货费 + 运费

更多信息：

值范围： 1 - 1000000000 USD / EUR

Show child parameters

orderProductType String REQUIRED

订单类型。可取值范围：

PRODUCT_INFO ：产品类型

productList Array<Product> REQUIRED

产品信息。

单次可上传不超过 30 种产品信息。

Show child parameters

sellerInfo Participant REQUIRED

卖家信息。

Show child parameters

buyerInfo Participant REQUIRED

买家信息。

Show child parameters

paymentTerm PaymentTerm REQUIRED

交易条款信息。

Show child parameters

shippingTerm ShippingTerm REQUIRED

物流条款信息。

Show child parameters

payResultNotifyUrl String REQUIRED

支付结果通知地址。

orderResultNotifyUrl String REQUIRED

订单扫描拒绝通知地址。

deliveryResultNotifyUrl String REQUIRED

发货审核结果通知地址。

memo String

附言。

该字段不支持以下特殊字符：: 和 /

更多信息：

最大长度：256 字符

出参

result Result REQUIRED

代表接口调用结果。

Show child parameters

tradeId String REQUIRED

WorldTrade系统生成的订单ID。

此字段只有当 result.resultStatus = S 时才会按需返回。

更多信息：

最大长度：64 字符

orderLink String REQUIRED

WolrdTrade返回给买家的订单链接信息。

此字段只有当 result.resultStatus = S 时才会按需返回。

orderPaymentLink String REQUIRED

WolrdTrade返回给买家的订单支付链接信息。

此字段只有当 result.resultStatus = S 时才会按需返回。

API Explorer

请求

URL

Case

Create trade order with correct parameters

请求体

响应

Case

Create trade order with correct parameters

响应体

响应处理

集成商调用接口后，万里汇返回集成商API调用结果。result.resultStatus 字段取值范围为：

result.resultStatus	描述
S	API请求成功。
F	API请求失败。失败原因参见结果码（即 result.resultCode 和 result.resultMessage ）或特殊结果码对照表。
U	API响应结果为`UNKNOWN`（未知）时，需重试API请求。重试策略：重试次数上限：7次重试时间间隔：5分钟、10分钟、20分钟、40分钟、80分钟、160分钟、320分钟如果问题依旧，请联系万里汇技术支持。

特殊结果码对照表

API 请求失败时，部分结果码将在 result.resultMessage 中返回具体的失败原因，即特殊结果码。

特殊结果码构成形式为：主码错误信息 | 主码编号+子码取值，如 The total order amount is invalid. | 003PC

请结合下述表格进行原因排查。如需人工介入，联系 WorldTrade 客户服务经理以解决此问题。

主码

错误信息	编号	入参定位路径
The total order amount is invalid.	001	`request.totalAmount`
The product list is invalid.	002	`request.productList`
The product name is invalid.	003	`request.productList.productName`
The product image file format is invalid.	004	`request.productList.imageFile`
The image file key is invalid.	005	`request.productList.imageFile.fileKey`
The image file name is invalid.	006	`request.productList.imageFile.fileName`
The product quantity is invalid.	007	`request.productList.specification.quantity`
The product unit code is invalid.	008	`request.productList.specification.unitCode`
The product unit price is invalid.	009	`request.productList.specification.unitAmount`
The total price of the product is invalid.	010	`request.productList.specification.totalAmount`
The product details is invalid.	011	`request.productList.specification.productDetail`
The product specification is invalid.	012	`request.productList.specification.specification`
The seller's email is invalid.	013	`request.sellerInfo.email`
The seller's name is invalid.	014	`request.sellerInfo.companyName`
The seller's address is invalid.	015	`request.sellerInfo.companyAddress`
The seller's residence province is invalid.	016	`request.sellerInfo.companyAddress.province`
The seller's website URL is invalid.	017	`request.sellerInfo.companyWebsite`
The seller's mobile area code is invalid.	018	`request.sellerInfo.mobileAreaCode`
The seller's phone number is invalid.	019	`request.sellerInfo.companyPhoneNumber`
The buyer's email is invalid.	020	`request.buyerInfo.email`
The buyer's name is invalid.	021	`request.buyerInfo.companyName`
The full payment amount is invalid.	022	`request.paymentTerm.fullAmount`
The discount amount is invalid.	023	`request.paymentTerm.discountAmount`
The discount rate is invalid.	024	`request.paymentTerm.discountRate`
The shipping days are invalid.	025	`request.shippingTerm.shippingRelativeDays`
The delivery country/region is invalid.	026	`request.shippingTerm.deliveryDestination.countryRegion`
The detailed delivery address is invalid.	027	`request.shippingTerm.deliveryDestination.detailedAddress`
The consignee name is invalid.	028	`request.shippingTerm.deliveryDestination.consigneeName`
The delivery postal code is invalid.	029	`request.shippingTerm.deliveryDestination.postalCode`
The consignee's mobile phone number is invalid.	030	`request.shippingTerm.deliveryDestination.mobilePhone`
The logistics insurance fee is invalid.	031	`request.shippingTerm.logisticsInsuranceFee`
The logistics inspection fee is invalid.	032	`request.shippingTerm.logisticsInspectionFee`
The shipping fee is invalid.	033	`request.shippingTerm.shippingFee`
The content of the memo is invalid.	034	`request.memo`

子码

取值	描述
ON	对象为空
LL	字符长度小于最小值
LG	字符长度大于最大值
PC	正则校验失败
AE	金额小于最小值
AG	金额大于最大值

result.resultCode：系统结果码

结果码	值	结果码信息	行动建议
SUCCESS	S	Success
PROCESS_FAIL	F	A general business failure occurred. Do Not retry.	需要人工介入，联系万里汇技术支持以解决此问题
PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.	确认请求正确加签
INVALID_SIGNATURE	F	The signature is invalid.	确认请求正确加签
REPEAT_REQ_INCONSISTENT	F	Repeated requests are inconsistent.	重试请求不一致，需保证所有请求参数均相同
UNKNOWN_EXCEPTION	U	API failed due to unknown reason.	服务器错误，若稍后重试问题依旧，联系万里汇技术支持以解决问题
FILE_SIZE_EXCEED_LIMIT	F	The file size has exceeded the limit.	文件大小需在允许范围内
CONTRACT_CHECK_FAIL	F	The contract check has failed.	检查合约状态后重试

result.resultCode：业务结果码

结果码	值	结果码信息	行动建议
AUTHORIZATION_NOT_EXIST	F	oauth not exist.	当前token授权关系不存在，请联系万里汇技术支持检查token授权关系。
ACCESS_TOKEN_EXPIRED	F	Access token has expired.	刷新token接口以重新获取访问令牌（access token），或联系万里汇技术支持以解决问题。
PERMISSION_NOT_GRANTED	F	The service is currently unavailable.	如有疑问，请联系您的客户经理
PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.	请参考特殊结果码对照表进行检查后重试。如需人工介入，联系WorldTrade客户服务经理以解决此问题。
SYSTEM_EXCEPTION	F	System exception.	需要人工介入，联系WorldTrade客户服务经理以解决此问题
USER_INFO_ERROR	F	The user information is incorrect.	确认买家及卖家相关信息无误后重试
ORDER_REJECTED	F	The order is rejected due to security concerns.	需要人工介入，联系WorldTrade客户服务经理以解决此问题
AMOUNT_ERROR	F	Incorrect order amount.	请修改订单相关金额后重试
EMAIL_ERROR	F	The seller's email and buyer's email cannot be identical.	使用不同的买家及卖家邮箱后重试
UNSUPPORTED_BUYER_EMAIL	F	The buyer's email is not supported.	需要人工介入，联系WorldTrade客户服务经理以解决此问题
REPEATED_REQUEST	F	Repeated request.	幂等请求，无需重试
FILE_NOT_EXIST	F	The file does not exist.	使用正确的文件信息后重试
DELIVERY_COUNTRY_ERROR	F	The country of shipment is wrong.	修改发货相关参数后重试
SELLER_COUNTRY_ERROR	F	The seller's country is wrong	确认sellerInfo.companyAddress.countryCode 参数传值正确后重试

字段名	是否必传	范例	说明
Client-Id	是	`Client-Id: *****`	关于这些参数的解释说明，详见：请求头。
Signature	是	`Signature: algorithm=RSA256, keyVersion=2, signature=*****`
Content-Type	是	`Content-Type: application/json; charset=UTF-8`
Request-Time	是	`Request-Time: 2019-04-04T12:08:56+08:00`
Access-Token	有条件要求	`Access-Token: ******`	注意此字段当用 OAUTH 授权时需要传递