Nationalization API - External Client Portal-- prueba prueba

Coordinadora Mercantil's API for automated management of the international cargo nationalization process, including customs clearance and last-mile delivery in Colombia. Through this API, external systems can create, query and group nationalization guides, managing both child guides (HAWB) and master guides (MAWB).

Services

Nationalization Guides (HAWB) Manages individual shipments. Allows registering batches of nationalization guides, querying their processing status and verifying that all guides were generated before continuing with the flow. Supports requests in both Spanish (/guias-hijas) and English (/hawb) with automatic field normalization.

Master Guides (MAWB) Manages the master airway bill that groups multiple child guides under the same shipment. Allows creating the MAWB, associating child guide batches, querying its status and enabling nationalization. The enablement step is irreversible and formally initiates the customs process. Supports Spanish (/guias-master) and English (/mawb).

Authentication

Before calling any endpoint you need an access token. Without it, every service will respond with HTTP 401 Unauthorized.

The token is valid for 60 minutes. When it expires, simply request a new one by repeating Step 1.

Don't have your credentials yet? Contact Coordinadora's Technology Department to receive your Client ID and Client Secret. Store them securely — never hardcode them in your source code.

Per-product access: credentials are specific to each product. A client_id issued for another Coordinadora service (for example, international shipping) will not have access to the Nationalization API, even if the credentials are valid. If you receive HTTP 401 with correct credentials, verify with the Coordinadora team that your client_id was enabled specifically for the Nationalization product.

Step 1 - Get your access token

Send a POST request to the authentication endpoint using your credentials via Basic Auth. Use the environment that applies to you:

How to build the request:

1. Method and path

POST /oauth/token

2. Headers

3. Request body

grant_type=client_credentials

What does the server respond?

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Copy the access_token value — you will use it in the next step.

Step 2 - Use the token in your requests

Add this header to every call you make to the API endpoints:

Authorization: Bearer <access_token>

What happens if the token fails?

Step 3 - Call the endpoints in order

This API follows a sequential 6-step flow. Each step depends on the previous one — none can be skipped:

⚠️ Step 6 is irreversible. Once nationalization is enabled, it is not possible to add more guides or modify the master guide. Make sure to complete and verify steps 2 through 5 before executing it.