Nacionalización · API externa
API Nacionalización
Gestión del proceso de nacionalización de guías (hijas, master y notificaciones).
Expuesta vía Apigee en api-dev.coordinadora.tech/nacionalizacion.
Autenticación con API Key en el header x-api-key.
¿Cuándo usarlo?
Para crear guías hijas, agruparlas bajo una guía master (MAWB), habilitar nacionalización aérea y disparar notificaciones.
Autenticación
Header x-api-key con el consumerKey de tu app en My Apps. Rate limiting por client-id.
Flujo de nacionalización (8 pasos)
1. Auth (x-api-key) — 2. GET /trm — 3. POST /guias-hijas — 4. GET /guias-hijas/{idLote} (polling) —
5. POST /guias-master — 6. POST /guias-master/hijas — 7. POST /guias-master/nacionalizacion ⚠️ irreversible —
8. POST /guias-hijas/declaracion-simplificada/{guia}.
[Guías hijas] Consultar estado de lote
Consulta estado del lote (paso 4 de 8). Lote completamente procesado cuando
guiasProceso = 0. Polling recomendado cada 5 s. Rate limiting: 50 solicitudes/min por client-id.
GET
/guias-hijas/{idLote}
v1.0.0
[Guías hijas] Crear guías de nacionalización
Permite enviar un lote de guías para iniciar el proceso de nacionalización (paso 3 de 8). Rate limiting: 10 requests/min por client-id. Body limit: 12 MB.
POST
/guias-hijas
v1.0.0
[Guías hijas] Declaraciones simplificadas (masivo)
Procesa todas las notificaciones pendientes de declaración simplificada (sin parámetros).
POST
/guias-hijas/declaracion-simplificada
v1.0.0
[Guías hijas] Declaración simplificada y notificación
Genera la declaración simplificada en PDF (subida a Cloud Storage, URL firmada 7 días) y envía la notificación al destinatario (paso 8 de 8).
POST
/guias-hijas/declaracion-simplificada/{guia}
v1.0.0
[Guías hijas] Limpiar guías hijas sin master
Elimina guías hijas con antigüedad superior a 120 días sin master asignado.
DELETE
/guias-hijas/sin_master
v1.0.0
[Guías hijas] Obtener TRM
Obtiene la Tasa de Representación del Mercado (TRM) desde Superfinanciera (paso 2 de 8). Se usa para calcular valoracionCop en POST /guias-hijas.
GET
/guias-hijas/trm
v1.0.0
[Guías master] Actualizar información complementaria
Actualiza dirección, nombre y teléfono del consignatario consultando Suite Clientes a partir del clienteDni.
POST
/guias-master/informacion_complementaria
v1.0.0
[Guías master] Asociar guías hijas
Asocia uno o más lotes de guías hijas a una guía master existente (paso 6 de 8). Máximo 5 lotes por solicitud. Rate limiting: 15 asociaciones/min por client-id.
POST
/guias-master/hijas
v1.0.0
[Guías master] Crear Guía Master
Crea una guía master (MAWB) que agrupa múltiples guías hijas (paso 5 de 8). Prerequisito: GET /guias-hijas/{idLote} debe retornar guiasProceso = 0. Rate limiting: 15 requests/min por client-id. Body limit: 1 MB.
POST
/guias-master
v1.0.0
[Guías master] Habilitar nacionalización ⚠️ IRREVERSIBLE
Activa el proceso de nacionalización para un MAWB (paso 7 de 8). ⚠️ Acción irreversible: una vez ejecutada no se pueden asociar más guías hijas ni modificar la master. Prerequisitos: master existente al menos un lote asociado. Rate limiting: 15 requests/min por client-id. Body limit: 512 KB.
POST
/guias-master/nacionalizacion
v1.0.0
[Notificaciones] Almacenar notificación
Registra una notificación; opcionalmente la envía si envio_automatico = true.
POST
/notificaciones
v1.0.0
[Notificaciones] Enviar notificación por ID
Ejecuta el envío de una notificación previamente registrada.
POST
/notificaciones/envio/{id}
v1.0.0
[Notificaciones] Registrar y notificar resultado de TRM
Registra resultado del proceso de TRM y envía notificación a destinatarios configurados.
POST
/notificaciones/trm
v1.0.0
[Notificaciones] Reporte de novedades por cliente
Consulta novedades de declaraciones agrupadas por cliente y publica mensajes a PubSub.
POST
/notificaciones/reporte_novedades
v1.0.0
[Notificaciones] Resumen diario de declaraciones
Genera resumen consolidado del estado de declaraciones para una fecha y notifica destinatarios.
POST
/notificaciones/resumen_declaracion/{fecha}
v1.0.0