Submit Trade Detail File

Endpoint: POST /v2/gc/collection-orders/trade-detail-uploads

Description: Submit a pre-uploaded transaction detail file to associate customs or trade settlement records with incoming collection activity.

Request

Request Body Field Descriptions (JSON)

Field Name	Type	Required	Description
requestId	string	Yes	Merchant-generated unique request ID (UUID recommended). Used for idempotency.
currency	string	Yes	Currency of the transaction detail file. Defaults to CNH if not specified.
detailPath	string	Yes	File path of the pre-uploaded transaction detail file. Must be a path returned by the File Upload API (POST /v2/gc/files/upload) using bizType=UPLOAD.
trxType	string	No	Type of customs transaction. Enum: CUSTOMS_RECEIPT, CUSTOMS_PRERECEIPT. Required when submitting customs-related detail files.
customsPath	string	No	File path of the pre-uploaded customs declaration file. Must be a path returned by the File Upload API (POST /v2/gc/files/upload). Required when trxType=CUSTOMS_RECEIPT.
notifyUrl	string	No	Merchant-hosted callback URL to receive the asynchronous upload processing result.

Request sample

{
  "requestId": "a9b0c1d2-3456-4ef7-8901-234567890bcd",
  "currency": "CNH",
  "detailPath": "gpt/UPLOAD/20240304/detail_a9b0c1d2.xlsx",
  "trxType": "CUSTOMS_RECEIPT",
  "customsPath": "gpt/CUSTOMS_RECEIPT/20240304/customs_a9b0c1d2.pdf",
  "notifyUrl": "https://merchant.example.com/webhooks/trade-detail"
}

Response

Response Field Descriptions

Field Name	Type	Description
code	number	Response code.
state	number	State of the response.
data	object	Trade detail upload submission result.
message	string	Response message.
neoResponseId	string	Unique NeoX response identifier.

data object fields:

Field Name	Type	Description
serialNum	string	NeoX serial number assigned to this trade detail upload submission for tracking purposes.

Response sample

{
  "code": 1,
  "state": 2,
  "data": {
    "serialNum": "TDU-20240304-000073"
  },
  "message": "Successful",
  "neoResponseId": "e5f6a7b8-9012-4cde-3456-789012345678"
}

Example cURL

curl -X POST "https://{base_url_openapi}/v2/gc/collection-orders/trade-detail-uploads" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "requestId": "a9b0c1d2-3456-4ef7-8901-234567890bcd",
    "currency": "CNH",
    "detailPath": "gpt/UPLOAD/20240304/detail_a9b0c1d2.xlsx",
    "trxType": "CUSTOMS_RECEIPT",
    "customsPath": "gpt/CUSTOMS_RECEIPT/20240304/customs_a9b0c1d2.pdf",
    "notifyUrl": "https://merchant.example.com/webhooks/trade-detail"
  }'

Notes

• Requires Bearer token in the Authorization header.

• The Accept-Language header can be used to specify the response language (Support: "vi", "en").

• Use a unique requestId for each request to avoid duplicate submissions.

• The request body must be in JSON format.

• detailPath must be a path value returned by the File Upload API (POST /v2/gc/files/upload) using bizType=UPLOAD.

• customsPath is required when trxType=CUSTOMS_RECEIPT and must be a path value returned by the File Upload API using bizType=CUSTOMS_RECEIPT.

• This is an asynchronous operation. The processing result is delivered to notifyUrl if provided. The returned serialNum can be used to track the submission status.