Get Custom code

Retrive Customs Code

This API allows external systems to retrieve customs codes from the system. External systems can either retrieve all customs codes in a paginated manner or specify a particular customs codes to fetch details for that specific code.

The API supports pagination to navigate through large lists of customs code.

Paginated Responses

The service is paginated to handle large sets of data efficiently.
For detailed information on how to handle pagination, refer to our Paginated Responses

Languages

The API response includes multilingual descriptions. The fields description_it and description_en provide VAT operation descriptions in Italian and English, respectively.

Manage languages

For detailed information on how to handle languages, refer to our Managing Languages

Actors

API Client: The system or user initiating the request.

4ws.trade: The backend system that processes the request.

Preconditions

The external system must have the necessary permissions and access to the service, please refer to Authentication.

Pagination parameters cursor and nextCursor must be correctly configured in the request.

Main Success Scenario

Case 1: Retrieving All Customs Codes

If the request is successful, the system will return an HTTP 200 response with the paginated list of customs codes and a nextCursor indicating whether there are more customs codes to retrieve. If nextCursor is setted, the external system must be call again, this service, setting cursor as nextCursor value.

Response Example

The nextCursor field indicates if there are more customs codes to be retrieved in the next pages, please refer to Paginated Responses how to manage next pages.

Case 2: Retrieving a Specific Customs codes

If the custom_code parameter is provided, the API will return the specific supplier that matches the provided code. The result is a single supplier object and without nextCursor.

Response Example

Alternate Flows

Authentication Error: If the client does not provide valid credentials, an error response is returned.

Error Example

Empty Result: If the custom_code is provided but not found, the API returns an HTTP 422 error with a message:

Error Example

Cursor & PageSize Used Together: Cursor and PageSize parameters in the request: If you specify a Cursor you cannot specify the page size. This information will already be contained within the cursor.

Error Example

Pagination Error: If invalid cursor parameters are provided, an error response is returned.

Rate Limiting: If the API rate limits are exceeded, the client must respect the retry interval indicated in the response headers Rate Limits.

Sequence Diagram

Case 1: Retrieving All Customs codes

Case 2: Retrieving a Specific Customs code

Best Practices

Please refer to Best Practices for Error Handling in External System for best practices on implementation.

Code Examples in Node.js

Example for fetching a paginated list of customs codes:

Example for fetching a specific customs code by custom_code:

Responses

🟢200Success

application/json

Body

Example

{
    "customCode": [
        {
            "custom_code": "string",
            "description_it": "string",
            "description_en": "string",
            "description_de": "string",
            "description_es": "string",
            "description_fr": "string",
            "description_pt": "string",
            "description_ru": "string",
            "description_ar": "string",
            "description_ja": "string",
            "description_zh": "string",
            "active": true,
            "net_weight": 19
        }
    ],
    "nextCursor": "eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTB2"
}

🟠422Invalid pageSize

🟠401Authentication failed

🟠403Operation not allowed

🟠404Custom category not found

Retrive Customs Code

Languages

Actors

Preconditions

Main Success Scenario

Case 1: Retrieving All Customs Codes

Case 2: Retrieving a Specific Customs codes

Alternate Flows

Sequence Diagram

Case 1: Retrieving All Customs codes

Case 2: Retrieving a Specific Customs code

Code Examples in Node.js

Request

Request Code Samples

Responses

Get Custom code

Retrive Customs Code#

Languages#

Actors#

Preconditions#

Main Success Scenario#

Case 1: Retrieving All Customs Codes#

Case 2: Retrieving a Specific Customs codes#

Alternate Flows#

Sequence Diagram#

Case 1: Retrieving All Customs codes#

Case 2: Retrieving a Specific Customs code#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Retrive Customs Code

Languages

Actors

Preconditions

Main Success Scenario

Case 1: Retrieving All Customs Codes

Case 2: Retrieving a Specific Customs codes

Alternate Flows

Sequence Diagram

Case 1: Retrieving All Customs codes

Case 2: Retrieving a Specific Customs code

Code Examples in Node.js