Create a trade orderSignature required

2026-02-04 06:31

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

Call this API to create a trade order.

Structure

Messages consist of a header and body. For details, see the following sections.

Request header

Field	Required	Sample	Description
Client-Id	Yes	`Client-Id: *****`	For more information about these request header fields, see Request header.
Signature	Yes	`Signature: algorithm=RSA256, keyVersion=2, signature=*****`
Content-Type	Yes	`Content-Type: application/json; charset=UTF-8`
Request-Time	Yes	`Request-Time: 2019-04-04T12:08:56+08:00`
Access-Token	Conditional	`Access-Token: ******`	Attention Required for OAUTH authorization.

Request parameters

requestId String REQUIRED

The unique ID that identifies the request to create a trade order. This parameter is idempotent.

More information:

Maximum length: 64 characters

exchangeFlag String REQUIRED

Indicates whether foreign exchange settlement is required. Valid values are:

Y: Settlement is required.
N: Settlement is not required.

commerceScene String CONDITIONAL

The trade export mode. Valid values are:

COMMON_TRADE : Cross-border e-commerce trade export mode (9610).
GENERAL_TRADE : General trade export mode (0110).

This parameter is required when exchangeFlag is Y.

totalAmount Amount REQUIRED

The total amount of the trade order.

Calculation formula:
When there is no discount on the order: totalAmount = productList.specification.totalAmount + logisticsInsuranceFee + logisticsInspectionFee + shippingFee
When there is a discount on the order, and the discountType is PERCENTAGE: totalAmount = productList.specification.totalAmount * (1 - discountRate / 100) + logisticsInsuranceFee + logisticsInspectionFee + shippingFee
When there is a discount on the order, and the discountType is AMOUNT: totalAmount = productList.specification.totalAmount - discountAmount + logisticsInsuranceFee + logisticsInspectionFee + shippingFee

More information:

Value range: 1 - 1000000000 USD / EUR

Show child parameters

orderProductType String REQUIRED

The type of the trade order.

Valid value is:

PRODUCT_INFO: a trade order with product information.

productList Array<Product> REQUIRED

The product information.

A maximum of 30 kinds of product information can be uploaded at a time.

Show child parameters

sellerInfo Participant REQUIRED

The seller information.

Show child parameters

buyerInfo Participant REQUIRED

The buyer information.

Show child parameters

paymentTerm PaymentTerm REQUIRED

The payment terms.

Show child parameters

shippingTerm ShippingTerm REQUIRED

The shipping terms.

Show child parameters

payResultNotifyUrl String REQUIRED

The callback URL specified by the Partner to receive payment results.

orderResultNotifyUrl String REQUIRED

The callback URL specified by the Partner to receive order results.

deliveryResultNotifyUrl String REQUIRED

The callback URL specified by the Partner to receive delivery results.

memo String

The order memo.

Special characters NOT supported are: : and /

More information:

Maximum length: 256 characters

Response parameters

result Result REQUIRED

The result of the API call.

Show child parameters

tradeId String REQUIRED

The unique trade ID assigned by WorldTrade.

This field is returned as needed only when result.resultStatus = S.

More information:

Maximum length: 64 characters

orderLink String REQUIRED

The order link returned to the buyer.

This field is returned as needed only when result.resultStatus = S.

orderPaymentLink String REQUIRED

The order payment link returned to the buyer.

This field is returned as needed only when result.resultStatus = S.

API Explorer

Request

URL

Case

Create trade order with correct parameters

Request Body

Response

Case

Create trade order with correct parameters

Response Body

Result processing logic

After calling the API, a response is returned. Possible values for result.resultStatus are:

Special Result Code Reference Table

When an API call fails, certain result codes will return specific failure reasons in the result.resultMessage field. Such result codes are referred to as special result codes.

The structure of a special result code is as follows: Main code error message | Main code number + subcode value. For example The total order amount is invalid. | 001PC

Use the following table to identify and troubleshoot the cause. If human intervention is needed, it is recommended that you contact WorldTrade customer service manager to resolve the issue.

Main code

Error message	Number	Request parameters location path
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`

Subcode

Value	Description
ON	The object is null.
LL	The character length is less than the minimum value.
LG	The character length exceeds the maximum value.
PC	The regular expression validation failed.
AE	The amount is less than the minimum value.
AG	The amount exceeds the maximum value.

System-related result codes

Code	Value	Message	Further action
SUCCESS	S	Success
PROCESS_FAIL	F	A general business failure occurred. Do Not retry.	Human intervention is usually needed. It is recommended that you contact our Technical Support Team to resolve the issue.
PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.	Check and verify whether the request fields, including the header fields and body fields, are correct and valid. For details on the fields of each API, see the specific API Structure section.
INVALID_SIGNATURE	F	The signature is invalid.	Make sure the request is properly signed with a valid signature.
REPEAT_REQ_INCONSISTENT	F	Repeated requests are inconsistent.	Ensure all the fields in the requests are the same and try again.
UNKNOWN_EXCEPTION	U	API failed due to unknown reason.	The service might be down, retry later. If the issue persists, contact our Technical Support Team.
FILE_SIZE_EXCEED_LIMIT	F	The file size has exceeded the limit.	Limit the file size to the allowable range.
CONTRACT_CHECK_FAIL	F	The contract check has failed.	Contact our Technical Support Team to check the status of your API contract. Make sure it is still valid and try again.

Business-related result codes

Code	Value	Message	Further action
AUTHORIZATION_NOT_EXIST	F	oauth not exist.	Make sure that the input is correct. If the issue persists, contact our Technical Support Team to verify the authorization status.
ACCESS_TOKEN_EXPIRED	F	Access token has expired.	Call the refreshToken API to refresh the access token or contact the WorldFirst Technical Support Team.
PERMISSION_NOT_GRANTED	F	The service is currently unavailable.	If you have any questions, please contact your account manager.
SYSTEM_EXCEPTION	F	System exception.	Contact the WorldTrade customer service manager for help.
PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.	Please refer to the special result code reference table to check and retry. If human intervention is needed, it is recommended that you contact WorldTrade customer service manager to resolve the issue.
USER_INFO_ERROR	F	The user information is incorrect.	Make sure that the seller and buyer's information is correct and call this API again.
ORDER_REJECTED	F	The order is rejected due to security concerns.	Contact the WorldTrade customer service manager for help.
AMOUNT_ERROR	F	Incorrect order amount.	Make sure that the order amount is correct and try calling this API again.
EMAIL_ERROR	F	The seller's email and buyer's email cannot be identical.	Use different email addresses for the seller and the buyer. Then, try calling this API again.
UNSUPPORTED_BUYER_EMAIL	F	The buyer's email is not supported.	Contact the WorldTrade customer service manager for help.
REPEATED_REQUEST	F	Repeated request.	This is an idempotent API that does not need to be called again. If necessary, use a different requestId to initiate another call.
FILE_NOT_EXIST	F	The file does not exist.	Use the correct file and call this API again.
DELIVERY_COUNTRY_ERROR	F	The country of shipment is wrong	Make sure that the delivery information is correct and call this API again.
SELLER_COUNTRY_ERROR	F	The seller's country is wrong	Make sure that the value of the sellerInfo.companyAddress.countryCode parameter is correct and call this API again.

Result status	Description
`S`	Indicates that the API call succeeded.
`F`	Indicates that the API call failed. For details, refer to result.resultCode or the special result code reference table below.
`U`	Indicates that the API call result is unknown. If this status is returned, the Partner may implement the following query strategy: Maximum 7 queries are allowed. Intervals between queries: 5 min, 10 min, 20 min, 40 min, 80 min, 160 min, and 320 min. If no queries succeed, contact our Technical Support Team.