GDE Orquestador API

Servicio orquestador de Gestión Dinámica de Envío (GDE). Expone operaciones para insertar, actualizar o eliminar el recaudo contra entrega de una guía, y para consultar la tipificación de campos permitidos por cliente.

Autenticación

Todas las rutas de negocio requieren Authorization: Bearer {access_token} obtenido en POST /oauth/token (flujo *client credentials*). Ver documentación de autenticación del API Gateway.

Consumidores de `POST /recaudo`

Perfil	Cabeceras de identidad	Comportamiento
Cliente externo	`nit` + `id_cliente` (obligatorios)	Valida cliente en BD, consulta AGW HTTP y federada detallada.
Suite Logística	`x-source` = `SHA-256(SOURCE_VALUE)`	No envía `nit` ni `id_cliente`; la identidad se resuelve desde la guía en federada (`identificacion`, `proceso`). Tipificación fija Coordinadora (solo código remisión 11 dígitos).

Si se envía x-source y su hash no coincide, la API responde 400 antes de procesar el body.

Acciones de recaudo (inferidas por `valor`)

`valor`	Acción	Notas
`> 0` sin recaudo previo	INSERT	Requiere `referenciaRecaudo` en el body.
`> 0` con recaudo previo	UPDATE	`referenciaRecaudo` opcional en body; en sync se usa la de federada.
`0`	DELETE	Elimina recaudo contra entrega (NS estándar).

Identificadores de solicitud

Cada respuesta incluye id (request ID de Fastify) para correlación con bitácora y logs.

Códigos de error frecuentes

Código	Significado
`BAD_MESSAGE`	Validación Zod (body o headers)
`DATA_ERROR`	Regla de negocio (tracking, acuerdo SIFA, población, vínculos, etc.)
`RR-INSERT-01`	Falta `referenciaRecaudo` en INSERT
`TRK-V1`	Estado de tracking no permite el cambio
`AC-V1`	Acuerdo SIFA de RCE no activo
`VP-01`	Población no válida para RCE
`TRANSACCION-E1`	Fallo al persistir cambio en CM
`DATABASE_ERROR`	Error de conexión a base de datos

Autenticación

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

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

Versión: v3.2.0
Base URL: https://api-test.coordinadora.tech/suite/guias
Autenticación: Bearer Token
Ambiente: API Gateway — entorno de pruebas (integración externa / Suite)

GET Consultar tipificación del cliente /orquestador/tipificacion v3.2.0 Devuelve qué campos del body de /recaudo puede usar el cliente identificado por nit (y id_cliente en headers). Indica si la guía se identifica por codigoRemision, referencia, referenciaDetalle o combinaciones. Nota: Suite Logística usa tipificación fija interna; este endpoint está orientado a clientes externos.

Ver docs

POST Insertar, actualizar o eliminar recaudo contra entrega /orquestador/recaudo v3.2.0 Orquesta el cambio de valor de recaudo (RCE) para una guía. Flujo cliente externo: valida nit id_cliente, tipificación en BD, consulta AGW y federada, luego tracking, población, acuerdo SIFA, vínculos y persistencia en CM/AGW según estado. Flujo Suite Logística: con x-source válido, resuelve identidad desde federada (identificacion → NIT, proceso → id_cliente), tipificación fija Coordinadora y pipeline común sin consulta AGW HTTP. Atajos: tracking 1 fuente AGW → Pub/Sub editarRecaudoAgw; tracking 1 fuente no AGW → sync federada directa.

Ver docs

APIs disponibles