# inquiryDeclarationRequests

> Use this API to inquire about the customs declaration status.

`POST /v1/customs/inquiryDeclarationRequests`

Use this API to inquire about the customs declaration status. 

# Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see： 

-   [Request header](https://docs.antom.com/ac/ams/api_fund.md#ML5ur)
-   [Response header](https://docs.antom.com/ac/ams/api_fund.md#WWH90)

> **Note**: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
>
> -   If the data type of a field is Integer and its value is `20`, set it as "`20`". 
> -   If the data type of a field is Boolean and its value is `true`, set it as "`true`".

## Request parameters

#### declarationRequestIds (Array<String>, REQUIRED)

The unique declaration request ID that is assigned by the merchant to identify a declaration request. Batch queries are supported, and up to 10 declaration request IDs are supported at a time.

More information:

- Maximum length: 32 characters
- Maximum size: 10 elements

## Response parameters

#### result (Result, REQUIRED)

The request result, which contains information such as status and error codes.

##### resultCode (String, REQUIRED)

Result code. Possible values are listed in the Result/Error codes table on this page.

More information:

- Maximum length: 64 characters

##### resultStatus (String, REQUIRED)

Result status. Valid values are:  

-   `S`: Indicates that the result status is successful. 
-   `F`: Indicates that the result status failed. 
-   `U`: Indicates that the result status is unknown.

##### resultMessage (String, REQUIRED)

Result message

More information:

- Maximum length: 256 characters

#### declarationRequestsNotFound (Array<String>)

The list of declaration request IDs that cannot be found in the system.

Note: This field is returned when _result.resultCode_ is `S` and one or more declaration request IDs cannot be found in the system.

More information:

- Maximum length: 32 characters
- Maximum size: 10 elements

#### declarationRecords (Array<DeclarationRecord>)

The list of customs declaration records. Each record represents a customs declaration.

> Note: This field is returned when _result.resultCode_ is `S`.

More information:

- Maximum size: 10 elements

##### declarationRequestId (String, REQUIRED)

The unique ID that is assigned by the merchant to identify a declaration request.

More information:

- Maximum length: 32 characters

##### customsPaymentId (String, REQUIRED)

The payment ID provided to the customs by the declaration service provider.

More information:

- Maximum length: 64 characters

##### customsOrderId (String, REQUIRED)

The order ID provided to the customs by the declaration service provider.

> Note: If the order is not split, this field is the same as _paymentRequestId_. If the order is split, this field is the same as _suborderId_.

More information:

- Maximum length: 64 characters

##### customs (CustomsInfo, REQUIRED)

The customs information

###### customsCode (String, REQUIRED)

Customs code. See the Customs Code section on this page for details .

More information:

- Maximum length: 28 characters

###### region (String, REQUIRED)

The customs region, which follows the 2-character [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country /region code.

> Note: Only the China customs region of `CN` is supported for now.

More information:

- Maximum length: 2 characters

##### merchantCustomsInfo (MerchantCustomsInfo, REQUIRED)

The merchant information that is registered in the customs system.

###### merchantCustomsCode (String, REQUIRED)

The merchant recordation number in the customs system.

More information:

- Maximum length: 128 characters

###### merchantCustomsName (String, REQUIRED)

The merchant recordation name in the customs system.

More information:

- Maximum length: 256 characters

##### declarationAmount (Amount, REQUIRED)

The declaration amount. Only China customs declaration is supported. The default currency is `CNY` (Chinese Renminbi).

###### currency (String, REQUIRED)

The 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.

More information:

- Maximum length: 3 characters

###### value (Integer, REQUIRED)

The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a 0-decimal currency).

> Note: For more information about the smallest currency unit, see [Currency codes](https://docs.antom.com/ac/ref/cc.md) for details.

More information:

- Value range: 0 - unlimited

##### splitOrder (Boolean, REQUIRED)

This field indicates whether the order is split for declaration.

##### declarationRequestStatus (String, REQUIRED)

The current status of this declaration order. Valid values are:

-   `IN_PROCESS`: The customs declaration application is still processing.
-   `CUSTOMS_PROCESSING_COMPLETED`: Successfully received by customs, and customs has returned the acceptance result.

##### lastModifiedTime (Datetime, REQUIRED)

The last status update time.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

##### customsDeclarationResultCode (String)

After the declaration is initiated, the result code is returned in the customs' receipt. Valid values are:

-   `2`: Declaration success and this result is recorded in the payment information.
-   `120`: The order, payment information, and the logistics number are verified correctly by the customs.
-   Numbers less than 0: Error occurred. Check with the target customs for more information.
-   `success`: The declaration is sent to customs successfully.

> Note: When the customs declaration request is sent to ZONGSHU and successfully confirmed as received, and the value of _declarationRequestStatus_ is `CUSTOMS_PROCESSING_COMPLETED`, Antom will accurately return the information of this field provided by customs.

More information:

- Maximum length: 64 characters

##### customsDeclarationResultDesc (String)

The description of the customs' returned result.

> Note:When the customs declaration request is sent to ZONGSHU and successfully confirmed as received, and the value of _declarationRequestStatus_ is `CUSTOMS_PROCESSING_COMPLETED`, Antom will accurately return the information of this field provided by customs.

More information:

- Maximum length: 2048 characters

##### customsDeclarationReturnTime (Datetime)

Customs' receipt return time.

> Note: This field is returned when _declarationRequestStatus_ is `CUSTOMS_PROCESSING_COMPLETED`.

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

## More information

This table shows details about the **customs code**:

| **Customs name** | **Unified customs solution** | **Customs code** | **Antom registration ID** |
| --- | --- | --- | --- |
| General Administration of Customs | Transmit to ZONGSHU | ZONGSHU | 31222699S7 |
| Henan bonded logistics center | Transmit to ZHENGZHOU | ZHENGZHOU | 31222699S7 |
| Ningbo Customs | Transmit to NINGBO | NINGBO | 31222699S7 |
| Xinzheng comprehensive bonded zone (Airport) | First transmit to HENAN, then to ZONGSHU | ZONGSHU | 31222699S7 |
| Tianjin Customs | Transmit to ZONGSHU | ZONGSHU | 31222699S7 |
| Shanghai Customs | Transmit to SHANGHAI\_CBT | SHANGHAI\_CBT | 31222699S7 |
| Guangzhou Customs (Airport) | Transmit to Guangzhou airport national inspection. The enterprise's filing information is required. | ZONGSHU | C000010000416158 |
| Guangzhou Customs (Nansha) | Transmit to Guangzhou Nansha national inspection. The enterprise's filing information is required. | ZONGSHU | C000010000416158 |
| Guangzhou Customs (Huangpu) | Transmit to Guangzhou Huangpu national inspection. The enterprise's filing information is required. | ZONGSHU | C000010000416158 |
| Guangzhou Customs (Shatian) | Transmit to Guangzhou Shatian national inspection. The enterprise's filing information is required. | ZONGSHU | C000010000416158 |
| Hangzhou Customs | Transmit to ZONGSHU | ZONGSHU | ZF14021901 |

## Result/Error codes

| Code | Value | Message | Further action |
| --- | --- | --- | --- |
| SUCCESS | S | Success | The interface is called successfully, no further action is needed. |
| ACCESS_DENIED | F | Access is denied. | Contact Antom Technical Support for detailed reasons. |
| INVALID_API | F | The called API is invalid or not active. | Contact Antom Technical Support to resolve the issue. |
| ARRAY_SIZE_EXCEEDED | F | One inquiry request only supports a maximum number of 10 declaration request IDs. | Check whether more than 10 declaration request IDs exist in the declarationRequestID field. |
| CLIENT_INVALID | F | The client ID is invalid. Antom has restrictions on client ID. | Check whether the client ID is correct, or contact Antom Technical Support for detailed reasons. |
| INVALID_CONTRACT | F | The parameter values in the contract do not match those in the current transaction. | Check whether the parameter values in the contract match those in the current transaction. If the values match, contact Antom Technical Support to troubleshoot the issue. |
| INVALID_SIGNATURE | F | The signature is not validated. The private key used to sign a request does not match the public key of Antom Dashboard. | Check whether the private key used to sign a request matches the public key of Antom Dashboard. The following signature references are useful:The signature field in a request header How to calculate a signature |
| KEY_NOT_FOUND | F | The private key or public key of Antom or the merchant is not found. | Check whether the private key or public key exists. If not, upload the private key in Antom Dashboard. |
| MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. | Check whether the media type is correct and use a media type that is accepted by Antom. |
| MERCHANT_NOT_REGISTERED | F | The merchant is not registered. | Please register the merchant by using the registration interface. Contact Antom Technical Support if failed to call the registration interface. |
| METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTP method. Only the POST method is supported. | Ensure the HTTP method is POST. |
| NO_INTERFACE_DEF | F | API is not defined. | Check whether the URL is correct. Please refer to the endpoint in the API documentation. |
| PARAM_ILLEGAL | F | The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong. | Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid. |
| PROCESS_FAIL | F | A general business failure occurred. | Do not retry. Human intervention is usually needed. It is recommended that you contact Antom Technical Support to troubleshoot the issue. |
| RISK_REJECT | F | The request is rejected because of the risk control. | Prompt the user that the request is rejected because the risk control failed. |
| SYSTEM_ERROR | F | A system error occurred. | Do not retry, and contact Antom Technical Support for more details. |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Call the API again to resolve the issue. If not resolved, contact Antom Technical Support. |
| UNKNOWN_EXCEPTION | U | An API call has failed, which is caused by unknown reasons. | Call the API again to resolve the issue. If not resolved, contact Antom Technical Support. |

## Request

```json
{
  "declarationRequestIds": [
    "o71cqM9BkRkTJZAVKkXSHM2m2KSfuVXQ"
  ]
}
```

## Response

### SUCCESS

```json
{
  "declarationRecords": [
    {
      "customs": {
        "customsCode": "ZONGSHU",
        "region": "CN"
      },
      "customsDeclarationResultCode": "success",
      "customsDeclarationResultDesc": "The customs declaration has been accepted. Thank you for your support.",
      "customsDeclarationReturnTime": "2021-11-09T22:23:58-08:00",
      "customsOrderId": "amsdmpay_shihao_jsh_20211110_153125_716",
      "customsPaymentId": "2021111022001447000514143531",
      "declarationAmount": {
        "currency": "CNY",
        "value": "100"
      },
      "declarationRequestId": "merchant_customs_00100",
      "declarationRequestStatus": "IN_PROCESS",
      "lastModifiedTime": "2021-11-23T18:04:44-08:00",
      "merchantCustomsInfo": {
        "merchantCustomsCode": "hangzhou_001",
        "merchantCustomsName": "Merchant's customs registration name_01"
      },
      "splitOrder": false
    }
  ],
  "declarationRequestsNotFound": [
    "merchant_customs_B",
    "merchant_customs_C"
  ],
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  }
}
```

### DECLARE_EXCEED_LIMIT

```json
{
  "result": {
    "resultCode": "ARRAY_SIZE_EXCEEDED",
    "resultMessage": "One inquiry request only supports a maximum number of 10 declaration request IDs.",
    "resultStatus": "F"
  }
}
```