API de Nacionalización - Portal para Clientes Externos

API de Coordinadora Mercantil para la gestión automatizada del proceso de nacionalización de mercancías internacionales, incluyendo el proceso aduanero y la entrega de última milla en Colombia. A través de esta API los sistemas externos pueden crear, consultar y agrupar guías de nacionalización, gestionando tanto guías hijas (HAWB) como guías master (MAWB).

Microservicios

Guías de Nacionalización (HAWB) Gestiona los envíos individuales. Permite registrar lotes de guías de nacionalización, consultar su estado de procesamiento y verificar que todas las guías fueron generadas antes de continuar con el flujo. Soporta requests en español (/guias-hijas) e inglés (/hawb) con normalización automática de campos.

Guías Master (MAWB) Gestiona la guía aérea maestra que agrupa múltiples guías hijas bajo un mismo embarque. Permite crear el MAWB, asociarle lotes de guías hijas, consultar su estado y habilitar la nacionalización. El paso de habilitación es irreversible e inicia formalmente el proceso aduanero. Soporta español (/guias-master) e inglés (/mawb).

Autenticación

Antes de consumir cualquier endpoint necesitas un token de acceso. Sin él, todos los servicios responden con HTTP 401 Unauthorized.

El token dura 60 minutos. Cuando expire, simplemente solicita uno nuevo repitiendo el Paso 1.

¿No tienes tus credenciales? Contáctate con el Departamento de Tecnología de Coordinadora para recibir tu Client ID y Client Secret. Guárdalas de forma segura — nunca las incluyas directamente en tu código.

Acceso por producto: las credenciales son específicas por producto. Un client_id emitido para otro servicio de Coordinadora (por ejemplo, envíos internacionales) no tendrá acceso a la API de Nacionalización, aunque las credenciales sean válidas. Si recibes HTTP 401 con credenciales correctas, verifica con el equipo de Coordinadora que tu client_id fue habilitado específicamente para el producto de Nacionalización.

Paso 1 - Obtener tu token de acceso

El token se obtiene enviando tus credenciales al endpoint de autenticación. Usa el ambiente que corresponda:

AmbienteURL
TESThttps://api-test.coordinadora.tech/oauth/token
PRODUCCIÓNhttps://api.coordinadora.tech/oauth/token

¿Cómo se construye la solicitud?

La solicitud tiene tres partes:

1. Método y ruta

POST /oauth/token

2. Headers

HeaderValorDescripción
AuthorizationBasic <base64(client_id:client_secret)>Tus credenciales codificadas. Postman e Insomnia hacen esto automático al elegir "Basic Auth".
Content-Typeapplication/x-www-form-urlencodedIndica el formato del cuerpo.

3. Cuerpo de la solicitud

grant_type=client_credentials

¿Qué responde el servidor?

CampoTipoDescripción
access_tokenstringEl token que debes usar en todas tus solicitudes.
token_typestringSiempre será Bearer.
expires_innúmeroTiempo de vigencia en segundos. 3600 = 60 minutos.
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Copia el valor de access_token — lo usarás en el siguiente paso.

Paso 2 - Usar el token en tus solicitudes

Agrega este header en cada llamada que hagas a los endpoints de la API:

Authorization: Bearer <access_token>

¿Qué pasa si el token falla?

SituaciónRespuestaSolución
Token no enviadoHTTP 401 UnauthorizedAgrega el header Authorization
Token inválidoHTTP 401 UnauthorizedVerifica que copiaste el token correctamente
Token expirado (> 3600s)HTTP 401 UnauthorizedVuelve al Paso 1 y obtén un token nuevo
client_id no habilitado para NacionalizaciónHTTP 401 UnauthorizedVerifica con el equipo de Coordinadora que tu client_id fue habilitado para este producto

Paso 3 - Consumir los endpoints en orden

Esta API sigue un flujo secuencial de 6 pasos. Cada paso depende del anterior:

PasoMétodoEndpoint¿Qué hace?Dato clave que retorna
1—/oauth/tokenObtener token de accesoaccess_token
2POST/guias-hijasCrear el lote de guías individualesid_lote
3GET/guias-hijas/{idLote}Verificar que el lote procesó correctamenteguiasProceso = 0
4POST/guias-masterCrear la guía master (MAWB)mawb
5POST/guias-master/hijasAsociar los lotes a la guía masterConfirmación
6POST/guias-master/nacionalizacionHabilitar la nacionalización ⚠️Confirmación final

⚠️ El paso 6 es irreversible. Una vez habilitada la nacionalización no es posible agregar más guías ni modificar la guía master. Completa y verifica los pasos 2 al 5 antes de ejecutarlo.

Autenticación

Tipo
Bearer Token
Flujo
OAuth2 Client Credentials
Header
Authorization: Bearer <token>

Para obtener un token utiliza el panel "Probar API".

Versión
v1.0.0
Base URL
https://api-dev.coordinadora.tech/nacionalizacion
Autenticación
Bearer Token
Ambiente
Producción y Sandbox

APIs disponibles

POST Asociar guías hijas a una guía master /guias-master/hijas v1.0.0 Permite asociar uno o más lotes de guías a una guía master existente. ⚠️ Precondición: Antes de asociar un lote, verificar mediante GET /guias-hijas/{idLote} que guiasProceso = 0. Se pueden asociar hasta 5 lotes por solicitud. Para más de 5 lotes, realizar múltiples llamadas. Rate limiting: 15 asociaciones por minuto por cliente. --- Paso 5 de 6 en el flujo de nacionalización: 1. Autenticación 2. POST /guias-hijas 3. GET /guias-hijas/{idLote} → verificar guiasProceso = 0 4. POST /guias-master 5. POST /guias-master/hijas ← AQUÍ 6. POST /guias-master/nacionalizacion --- 🔐 Autenticación requerida | | | |---|---| | Header | Authorization: Bearer <access_token> | | Token (TEST) | POST https://api-test.coordinadora.tech/oauth/token | | Token (PROD) | POST https://api.coordinadora.tech/oauth/token | | Método | Basic Auth — Client ID como usuario, Client Secret como contraseña | | Body | Content-Type: application/x-www-form-urlencoded · grant_type=client_credentials | | Vigencia | 3600 segundos | | HTTP 401 | Token no enviado, inválido o expirado | Las credenciales (Client ID y Client Secret) son entregadas por el Departamento de Tecnología de Coordinadora.
Ver docs
GET Consultar estado de un lote de guías /guias-hijas/{idLote} v1.0.0 Permite consultar el estado actual de un lote de guías previamente creado. El lote se considera completamente procesado cuando guiasProceso es igual a 0. En ese punto, guiasGeneradas guiasFallidas debe ser igual a totalGuias. Rate limiting: 50 solicitudes por minuto por cliente. Buena práctica: implementar intervalo mínimo de 2 segundos entre consultas. --- Paso 3 de 6 en el flujo de nacionalización: 1. Autenticación 2. POST /guias-hijas → se obtiene el id_lote 3. GET /guias-hijas/{idLote} ← AQUÍ — consultar estado del lote creado 4. POST /guias-master 5. POST /guias-master/hijas 6. POST /guias-master/nacionalizacion --- 🔐 Autenticación requerida | | | |---|---| | Header | Authorization: Bearer <access_token> | | Token (TEST) | POST https://api-test.coordinadora.tech/oauth/token | | Token (PROD) | POST https://api.coordinadora.tech/oauth/token | | Método | Basic Auth — Client ID como usuario, Client Secret como contraseña | | Body | Content-Type: application/x-www-form-urlencoded · grant_type=client_credentials | | Vigencia | 3600 segundos | | HTTP 401 | Token no enviado, inválido o expirado | Las credenciales (Client ID y Client Secret) son entregadas por el Departamento de Tecnología de Coordinadora.
Ver docs
GET Consultar guías master por cliente y fechas /guias-master/clientes/{identificacion}/guias v1.0.0 Retorna la lista paginada de guías master asociadas a un cliente, filtradas por rango de fechas. El rango máximo entre fecha_inicio y fecha_fin es de 6 meses. Rate limiting: 10 solicitudes por minuto por cliente. --- Puede consultarse en cualquier momento después de crear guías master con POST /guias-master. --- 🔐 Autenticación requerida | | | |---|---| | Header | Authorization: Bearer <access_token> | | Token (TEST) | POST https://api-test.coordinadora.tech/oauth/token | | Token (PROD) | POST https://api.coordinadora.tech/oauth/token | | Método | Basic Auth — Client ID como usuario, Client Secret como contraseña | | Body | Content-Type: application/x-www-form-urlencoded · grant_type=client_credentials | | Vigencia | 3600 segundos | | HTTP 401 | Token no enviado, inválido o expirado | Las credenciales (Client ID y Client Secret) son entregadas por el Departamento de Tecnología de Coordinadora.
Ver docs
POST Crear un lote de guías de nacionalización /guias-hijas v1.0.0 Permite a los clientes enviar un lote de guías para iniciar su proceso de nacionalización. El sistema procesa la información de cada guía, valida los datos y retorna un identificador para el seguimiento del lote. Rate limiting: 20.000 guías por minuto por cliente. Al exceder: HTTP 429. --- Paso 2 de 6 en el flujo de nacionalización: 1. Autenticación 2. POST /guias-hijas ← AQUÍ 3. GET /guias-hijas/{idLote} 4. POST /guias-master 5. POST /guias-master/hijas 6. POST /guias-master/nacionalizacion --- 🔐 Autenticación requerida | | | |---|---| | Header | Authorization: Bearer <access_token> | | Token (TEST) | POST https://api-test.coordinadora.tech/oauth/token | | Token (PROD) | POST https://api.coordinadora.tech/oauth/token | | Método | Basic Auth — Client ID como usuario, Client Secret como contraseña | | Body | Content-Type: application/x-www-form-urlencoded · grant_type=client_credentials | | Vigencia | 3600 segundos | | HTTP 401 | Token no enviado, inválido o expirado | Las credenciales (Client ID y Client Secret) son entregadas por el Departamento de Tecnología de Coordinadora.
Ver docs
POST Crear una guía master /guias-master v1.0.0 Permite crear una guía master que agrupa múltiples guías bajo un mismo MAWB. Rate limiting: 15 guías master por minuto por cliente. --- Paso 4 de 6 en el flujo de nacionalización: 1. Autenticación 2. POST /guias-hijas 3. GET /guias-hijas/{idLote} 4. POST /guias-master ← AQUÍ 5. POST /guias-master/hijas 6. POST /guias-master/nacionalizacion --- 🔐 Autenticación requerida | | | |---|---| | Header | Authorization: Bearer <access_token> | | Token (TEST) | POST https://api-test.coordinadora.tech/oauth/token | | Token (PROD) | POST https://api.coordinadora.tech/oauth/token | | Método | Basic Auth — Client ID como usuario, Client Secret como contraseña | | Body | Content-Type: application/x-www-form-urlencoded · grant_type=client_credentials | | Vigencia | 3600 segundos | | HTTP 401 | Token no enviado, inválido o expirado | Las credenciales (Client ID y Client Secret) son entregadas por el Departamento de Tecnología de Coordinadora.
Ver docs
POST Habilitar nacionalización de una guía master /guias-master/nacionalizacion v1.0.0 Activa el proceso de nacionalización para un MAWB específico. ⚠️ Acción irreversible: Una vez ejecutada, no es posible asociar más guías hijas ni modificar el contenido de la guía master. Asegúrese de que todas las guías hijas necesarias estén correctamente asociadas antes de ejecutar este endpoint. Rate limiting: 15 habilitaciones por minuto por cliente. --- Paso 6 de 6 en el flujo de nacionalización (paso final e irreversible): 1. Autenticación 2. POST /guias-hijas 3. GET /guias-hijas/{idLote} → verificar guiasProceso = 0 4. POST /guias-master 5. POST /guias-master/hijas → verificar que todos los lotes estén asociados 6. POST /guias-master/nacionalizacion ← AQUÍ ✅ Precondiciones requeridas: La guía master debe existir y haber sido creada correctamente Al menos un lote de guías hijas debe estar asociado a la master Todos los lotes deben estar asociados antes de ejecutar — la operación es irreversible --- 🔐 Autenticación requerida | | | |---|---| | Header | Authorization: Bearer <access_token> | | Token (TEST) | POST https://api-test.coordinadora.tech/oauth/token | | Token (PROD) | POST https://api.coordinadora.tech/oauth/token | | Método | Basic Auth — Client ID como usuario, Client Secret como contraseña | | Body | Content-Type: application/x-www-form-urlencoded · grant_type=client_credentials | | Vigencia | 3600 segundos | | HTTP 401 | Token no enviado, inválido o expirado | Las credenciales (Client ID y Client Secret) son entregadas por el Departamento de Tecnología de Coordinadora.
Ver docs

Mostrando 6 de 6 endpoints