submitTradeOrder
POST
: /amsin/api/v1/business/account/submitTradeOrder
集成商可以调用此接口提交交易订单。在提交交易订单的同时,集成商还需调用 submitAttachment 接口提交相关附件。关于提交附件的更多信息,参见 submitAttachment。
此接口适用于以下两种业务场景:
- B2C 场景
- B2B 场景
接口结构
万里汇接口的报文结构包括:请求头、请求体、响应头和响应体。该章节主要介绍请求体和响应体的结构。关于请求头和响应头的更多信息,参见:
请求参数
字段名 | 数据类型 | 是否必填 | 描述 |
requestId | 字符串 | 是 | 针对单次交易订单上传请求,由集成商指定的唯一请求号。 更多信息:
|
sceneCode | 字符串 | 是 | 业务场景代码。可取值如下:
|
quotaAccumulationMethod | 字符串 | 是 | 申报额度的累计方式。 可取值如下:
|
quotaAccumulationId | 字符串 | 是 | 申报额度的累计标识。此字段的赋值规则如下:
|
tradeOrders | 数组<TradeOrder 对象> | 是 | 交易订单列表。此字段的赋值条件如下:
|
platform | 字符串 | 有使用条件 | 交易发生平台,用于标识外部来源。当 sceneCode = |
notifyUrl | 字符串 | 否 | 交易订单提交结果的异步通知地址。 更多信息:
|
extendInfo | 字符串 | 否 | 额外信息。 更多信息:
|
响应参数
字段名 | 数据类型 | 是否必填 | 描述 |
result | Result 对象 | 是 | API 调用结果,即交易订单上传的请求结果。 |
requestId | 字符串 | 是 | 针对单次交易订单上传请求,由集成商指定的唯一请求号。 更多信息:
|
acceptOrderId | 字符串 | 有使用条件 | 针对单次交易订单提交请求,由万里汇指定的受理单号。当 sceneCode = 更多信息:
|
tradeOrderResult | 数组 <TradeOrderResult> 对象 | 有使用条件 | 所受理的交易订单信息,包括交易单号、订单状态等。当 sceneCode = |
响应处理
集成商调用接口后,万里汇通过 result.resultStatus 字段返回集成商 API 调用结果。此字段的取值范围如下:
result.resultStatus | 描述 |
| API请求成功。 |
| API请求失败。具体失败原因,参见结果码(即 result.resultCode 和 result.resultMessage)。 |
| API响应结果为 重试策略:
如果问题依旧,请联系万里汇技术支持。 |
结果码
result.resultCode
resultCode | resultStatus | resultMessage | resultMessage 中文含义 | 处理建议 |
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. | 参数异常 | 修改订单信息、更换requestId,发起重试 |
INVALID_SIGNATURE | F | The signature is invalid. | 签名校验失败 | 确认请求正确加签,更换requestId,发起重试 |
REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. | 幂等请求 | 幂等请求,无需重试 |
UNKNOWN_EXCEPTION | U | The API call is failed, which is caused by unknown reasons. | 未知错误 | 无需更换requestId,发起重试 |
FUND_ORDER_NOT_EXIST | F | The fund order does not exit. | 资金单不存在 | 联系万里汇技术支持以解决此问题 |
ACCESS_DENIED | F | Access is denied for submitting trade orders. | 没有操作权限 | 联系万里汇技术支持以解决此问题 |
ORDER_COUNT_EXCEED_LIMIT | F | The number of associated trade orders exceeds limit. | 订单关联条数超过上限 | 修改订单同步条数,更换订单reqeustId,发起重试 |
WRONG_TRADE_TYPE | F | tradeType is not supported, or tradeType values are inconsistent across trade orders. | 订单贸易类型不支持,或 参数贸易类型不一致 | 联系万里汇技术支持以解决此问题 |
REQUEST_PARAM_AMOUNT_ERROR | F | Invalid amount parameter exists. | 参数金额异常 | 修改订单或关联信息,更换订单 reqeustId,发起重试。 |
TRADE_ORDER_AUTH_STATUS_ILLEGAL | F | Associated trade order already exists, and its verification has not passed. | 订单已经存在,且审核拒绝或者审核需补件 | 联系万里汇技术支持以解决此问题 |
RELATE_AMOUNT_ERROR | F | The intended association amount is incorrect. | 关联金额异常 | 修改订单关联金额,更换订单reqeustId,发起重试。 注:不可修改已上传成功的订单金额 |
ENTITY_REGISTRATION_REQUIRED | F | Entity registration is required for uploading customs declaration. | 需要同步报关单,没有完成关联主体登记 | 联系万里汇技术支持以解决此问题 |
INCONSISTENT_TRADE_TYPE | F | tradeType values are inconsistent for partial associations of the same collection order. | 订单再次部分关联时和历史关联订单贸易类型不一致 | 联系万里汇技术支持以解决此问题 |
UN_SUPPORT_BUSINESS | F | Unsupported business. | 包含无效参数 | 包含无效参数,使用正确参数重试 |
CONTRACT_CHECK_FAIL | F | The contract check has failed. | 合约状态异常 | 检查合约状态后重试 |
REGULATED_COUNTRY_NOT_SUPPORTED | F | The tradeCountry or deliverCountry of the trade order is not supported. We do not support the order temporarily for the safety of customers' funds. | 为了您的资金安全,我们暂不支持买家国家(tradeCountry) 或收货国家(deliverCountry)为受管制国家的订单。 | 查看受管制国家的完整名单,点击参数介绍。详情请咨询万里汇技术支持。 |
REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. | 存在重复且不一致请求。 | 确保请求中相同字段赋值一致后重试 |
FUND_ORDER_RELATED_MANUALLY | F | Fund order has already been manually related to the trade order. | 资金单已被手动关联至交易单。 | 检查已关联的资金单是否正确,若无误则无需重复关联资金单。 |
代码示例
示例一:B2C 场景
请求体
{
"requestId": "20230222191210001100300007*****",
"sceneCode": "PAY_INTO_CHINA",
"quotaAccumulationMethod": "USER_ID",
"quotaAccumulationId": "21201200791*****",
"platform": "AE",
"tradeOrders": [
{
"referenceOrderNo": "50957342066*****",
"orderTime": "2023-01-10T21:18:24Z",
"paymentTime": "2023-01-10T21:28:24Z",
"orderType": "LOAN",
"tradeType": "GOODS",
"tradeAmount": {
"value": 500,
"currency": "USD"
},
"transAmount": {
"value": 500,
"currency": "USD"
},
"merchant": {
"store": {
"storeShopUrl": "//www.aliexpress.com/store/56*****"
}
},
"buyer": {
"referenceBuyerId": "7175*****",
"buyerName": {
"fullName": "ekaterina tsip*****"
}
},
"goods": [
{
"goodsName": "*****",
"goodsCategory": "Jewelry & Access*****",
"goodsQuantity": "1"
}
],
"shipping": {
"wayBillInfos": [
{
"shippingOrderReferenceNo": "RM450941*****",
"shippingAddress": {
"address1": "Калининград г, Калининградская обл, Менделее*****",
"city": "Калининг*****",
"region": "RU"
}
}
]
}
}
]
}
响应体
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "success."
},
"requestId": "20230222191210001100300007*****",
"tradeOrderResults": [
{
"referenceOrderNo": "50957342066*****",
"orderStatus": "ACCEPT",
"statusMessage": "Accepted, pending process."
}
]
}
示例二:B2C 场景
请求体
{
"requestId": "20230222191210001100300007*****",
"sceneCode": "PAY_INTO_CHINA",
"quotaAccumulationMethod": "RECEIVING_ACCOUNT",
"quotaAccumulationId": "7276*****",
"platform": "AE",
"tradeOrders": [
{
"referenceOrderNo": "2810241509776641178*****",
"orderTime": "2023-01-10T21:18:24Z",
"paymentTime": "2023-01-10T21:28:24Z",
"orderType": "LOAN",
"tradeType": "GOODS",
"tradeAmount": {
"value": 500,
"currency": "USD"
},
"transAmount": {
"value": 500,
"currency": "USD"
},
"merchant": {
"store": {
"storeShopUrl": "//www.aliexpress.com/store/56*****"
}
},
"buyer": {
"buyerName": {
"fullName": "MICROSOFT"
}
},
"goods": [
{
"goodsName": "*****",
"goodsCategory": "Jewelry & Access*****",
"goodsQuantity": "1"
}
],
"shipping": {
"wayBillInfos": [
{
"shippingOrderReferenceNo": "RM450941*****",
"shippingAddress": {
"address1": "Калининград г, Калининградская обл, Менделее*****",
"city": "Калининг*****",
"region": "RU"
}
}
]
}
}
]
}
响应体
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "success."
},
"requestId": "20230222191210001100300007*****",
"tradeOrderResults": [
{
"referenceOrderNo": "2810241509776641178*****",
"orderStatus": "ACCEPT",
"statusMessage": "Accepted, pending process."
}
]
}
示例三:B2C 场景
请求体
{
"requestId": "20230222191210001100300007*****",
"sceneCode": "PAY_INTO_CHINA",
"quotaAccumulationMethod": "BENEFICIARY",
"quotaAccumulationId": "7276*****",
"platform": "MICROSOFT",
"tradeOrders": [
{
"referenceOrderNo": "50957342066*****",
"orderTime": "2023-04-21T22:18:24Z",
"paymentTime": "2023-04-21T22:18:24Z",
"orderType": "LOAN",
"tradeType": "SERVICE",
"tradeAmount": {
"value": 500,
"currency": "USD"
},
"transAmount": {
"value": 500,
"currency": "USD"
},
"revenueShare": "100",
"buyer": {
"buyerName": {
"fullName": "MICROSOFT"
}
},
"seller": {
"customerName": "David*****"
},
"goods": [
{
"goodsName": "ARTICAL_DISPLAY",
"goodsQuantity": "125***"
}
],
"market": "CHN"
}
]
}
响应体
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "success."
},
"requestId": "20230222191210001100300007*****",
"tradeOrderResults": [
{
"referenceOrderNo": "50957342066*****",
"orderStatus": "ACCEPT",
"statusMessage": "Accepted, pending process."
}
]
}
示例四:B2B 场景
请求体
{
"requestId": "16782687*****",
"sceneCode": "CREATE_B2B_ORDERS",
"quotaAccumulationMethod": "TRANSFER_ID",
"quotaAccumulationId": "20230308191210001100300007*****",
"tradeOrders": [
{
"referenceOrderNo": "trade_order16782687*****",
"tradeType": "GOODS",
"orderTime": "2023-01-10T21:18:24Z",
"isUsedForExchange": "Y",
"tradeAmount": {
"currency": "USD",
"value": "2999"
},
"transAmount": {
"currency": "USD",
"value": "2999"
},
"bizContractInfo": {
"buyerEnName": "阿联*****",
"contractList": [
{
"fileKey": "sd*****",
"fileName": "sa*****"
}
],
"deliverCountry": "JP",
"tradeCountry": "JP"
},
"goods": [
{
"goodsCnName": "微软*****",
"goodsName": "Microsoft Ergonomic Keyboard (LXM-0*****",
"goodsQuantity": "3",
"goodsUnit": "KG",
"storeUrl": "http://sd*****"
}
],
"shipping": {
"expectedShippingDate": "16594306*****",
"isDeclared": "N",
"isNewBuyer": "N",
"isShipped": "N",
"tradeTerms": "CFR",
"wayBillInfos": [
{
"logisticsCompany": {
"providerKey": "HYESL",
"providerValue": "阿联酋*****"
},
"shippingMethod": "RAILWAY",
"shippingOrderReferenceNo": "12*****",
"shippingProofAttachmentList": [
{
"fileKey": "sd*****",
"fileName": "sa*****"
}
]
}
]
},
"storeWebSites": {
"fileKey": "sd*****",
"fileName": "sa*****"
},
"otherAttachmentList": [
{
"fileKey": "remarkfilefi*****",
"fileName": "remarkfilefil*****"
}
],
"attachmentDesc": "123*****"
}
]
}
响应体
{
"acceptOrderId": "20230308191680008004600000*****",
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "success."
}
}