API Guías Anticipadas Coordinadora Interno

📌 Documentación de la API de Guías Anticipadas Coordinadora

📝 Descripción:

  • Esta API de Guías Anticipadas permite gestionar paquetes de guías anticipadas y órdenes de compra

para clientes de Coordinadora, soportando consulta de paquetes disponibles y administración del carrito.

✨ Funcionalidades principales:

  • 📦 Consulta de paquetes de guías anticipadas disponibles por cliente
  • 📋 Consulta de inventario de paquetes comprados por NIT y división
  • 🛒 Gestión de órdenes de compra (carrito): listar, agregar y actualizar unidades
  • 🔍 Consulta y creación de ejemplos (módulo demo multi-BD)
  • 🏥 Health checks del servicio

🔒 Autenticación:

  • 🔑 Se requiere un token de autenticación válido como Bearer Token en el header Authorization.
  Authorization: Bearer <token>

📊 Endpoints principales:

MétodoEndpointDescripción
GET/paquetesConsulta paquetes activos por país, NIT y división
GET/inventarioConsulta inventario de paquetes por NIT y división
GET/ordenes-compras/historialHistorial paginado de órdenes (excluye CARRITO)
GET/ordenes-comprasLista órdenes/carrito por NIT, estado y email
POST/ordenes-comprasAgrega un paquete al carrito
PUT/ordenes-comprasActualiza unidades de un paquete en el carrito
DELETE/ordenes-comprasVacía el carrito del cliente
POST/ordenes-compras/proceder-pagoInicia checkout de pago (OpenPay)
POST/ordenes-compras/validar-pagoConsulta estado de orden por transacción
POST/ordenes-compras/estado-transaccionWebhook de notificación de transacción (OpenPay)
GET/ordenes-compras/sincronizarSincroniza estados de órdenes pendientes (OpenPay)
GET/maestros/cfdiCatálogo de usos CFDI para facturación
GET/notificaciones/resilienciaReprocesa notificaciones stage pendientes
GET/notificaciones/facturacion/{id}Procesa notificación stage destino facturación
GET/ejemplosLista todos los ejemplos registrados
POST/ejemplosCrea un nuevo ejemplo
GET/ejemplos/eventosLista eventos registrados de ejemplos
GET/healthHealth check básico del servicio
GET/health/detailedHealth check detallado del servicio

🔗 Fuente de verdad de contratos (entrada/salida)

Los esquemas de request y response de esta especificación están alineados con el microservicio cm-guias-anticipadas-ms. Ante cualquier discrepancia, prevalece el código del MS:

Módulo MSDTOs (entrada)Entidades (salida)
paquetessrc/modules/paquetes/dto/obtener-paquetes.dto.tssrc/modules/paquetes/domain/entities/paquete.entity.ts
inventariosrc/modules/inventario/dto/obtener-inventario.dto.tsrepositorio / mapeo en inventario
ordenes-comprassrc/modules/ordenes-compras/dto/*.dto.tssrc/modules/ordenes-compras/domain/entities/carrito-paquete.entity.ts
maestros—src/modules/maestros/domain/entities/cfdi.entity.ts
notificacionessrc/modules/notificaciones/dto/*.dto.tsmensajes string en data

🌐 Especificaciones Generales:

  • Versión: 1.0.0
  • Protocolo: HTTPS
  • Base URL: https://guias-anticipadas-services-test.coordinadora.com (sin prefijo /api/v1; ej. https://guias-anticipadas-services-test.coordinadora.com/notificaciones/resiliencia)
  • Formato de respuesta: JSON
  • Autenticación: Bearer Token (JWT)
  • Estándar de API: OpenAPI 3.0

Autenticación

Tipo
Bearer Token
Header
Authorization: Bearer <token>
Versión
v1.0.0
Base URL
https://guias-anticipadas-services-test.coordinadora.com
Autenticación
Bearer Token
Ambiente
Servidor según ambiente (dev, test o prod). `guias-anticipadas-services-test.coordinadora.com` se define sin protocolo; el pipeline antepone `https://`.

APIs disponibles

PUT ✏️ Actualizar Unidades de Paquete en el Carrito /ordenes-compras v1.0.0 📝 Descripción: Endpoint utilizado para actualizar la cantidad de unidades de un paquete dentro de una orden de compra existente. Si unidades es 0, la línea del paquete se elimina del carrito. 🔒 Autenticación: 🔑 Se requiere un token de autenticación válido como Bearer Token en el header Authorization. `` Authorization: Bearer <token> ``
Ver docs
POST ✏️ Crear Ejemplo /ejemplos v1.0.0 📝 Descripción: Endpoint utilizado para crear un nuevo ejemplo. El nombre debe ser único y alfanumérico; la descripción debe ser más larga que el nombre. 🔒 Autenticación: 🔑 Se requiere un token de autenticación válido como Bearer Token en el header Authorization. `` Authorization: Bearer <token> ``
Ver docs
POST ➕ Agregar Paquete al Carrito /ordenes-compras v1.0.0 📝 Descripción: Endpoint utilizado para agregar un paquete al carrito de órdenes de compra de un cliente. 🔒 Autenticación: 🔑 Se requiere un token de autenticación válido como Bearer Token en el header Authorization. `` Authorization: Bearer <token> ``
Ver docs
GET 🏥 Health Check Básico /health v1.0.0 📝 Descripción: Endpoint de verificación básica del estado del servicio. No requiere autenticación.
Ver docs
GET 🏥 Health Check Detallado /health/detailed v1.0.0 📝 Descripción: Endpoint de verificación detallada del estado del servicio, incluyendo conexiones a bases de datos y dependencias. No requiere autenticación.
Ver docs
POST 💳 Proceder al Pago (OpenPay) /ordenes-compras/proceder-pago v1.0.0 Inicia el checkout de pago para una orden en carrito. Contrato: ProcederPagoBodySchema en cm-guias-anticipadas-ms.
Ver docs
GET 📋 Consulta Inventario de Guías Anticipadas /inventario v1.0.0 📝 Descripción: Retorna los paquetes en inventario del cliente para el NIT (y división si aplica). Solo incluye registros con cantidad_guias_disponible > 0 (paquetes agotados no se listan). Los nombres de los campos en la respuesta coinciden con las columnas de BD / contrato del microservicio. 📦 Campos de cada ítem (data[]): | Campo | Origen | |-------|--------| | id_inventario | guias_anticipadas.inventarios.id_inventario | | peso_paquete | guias_anticipadas.paquetes.peso_paquete | | id_zona | guias_anticipadas.paquetes.id_zona | | nombre_zona | guias_anticipadas.zonas.nombre_zona | | fecha_hora_expiracion | guias_anticipadas.inventarios.fecha_hora_expiracion (formato YYYY-MM-DD) | | cantidad_guias | guias_anticipadas.paquetes.cantidad_guias | | cantidad_guias_disponible | guias_anticipadas.inventarios.cantidad_guias_disponible | | guias_usadas | Calculado: cantidad_guias cantidad_guias_disponible | | esta_expirado | Calculado en backend según fecha_hora_expiracion | 🔒 Autenticación: 🔑 Se requiere un token de autenticación válido como Bearer Token en el header Authorization. `` Authorization: Bearer <token> ``
Ver docs
GET 📋 Lista Todos los Ejemplos /ejemplos v1.0.0 📝 Descripción: Endpoint utilizado para obtener todos los ejemplos registrados en el sistema. 🔒 Autenticación: 🔑 Se requiere un token de autenticación válido como Bearer Token en el header Authorization. `` Authorization: Bearer <token> ``
Ver docs
GET 📑 Catálogo CFDI /maestros/cfdi v1.0.0 Retorna el catálogo de usos CFDI disponibles para facturación. Salida: CfdiEntity.toJSON() en cm-guias-anticipadas-ms.
Ver docs
GET 📜 Historial de Órdenes de Compra /ordenes-compras/historial v1.0.0 Lista paginada de órdenes de compra del cliente excluyendo estado CARRITO. Consulta solo la tabla ordenes_compras (sin join a detalles/paquetes). Contrato query: ListarHistorialOrdenesComprasQuerySchema en cm-guias-anticipadas-ms (listar-historial-ordenes-compras.dto.ts). Notas de exposición Path Istio en este gateway: GET /ordenes-compras/historial (rewrite al MS). No es el target de Locust. La prueba de carga (flujo-17 / CA-014) apunta al endpoint público de suite-backend: GET /guias-anticipadas/ordenes-compras/historial. 🔒 Autenticación: 🔑 Bearer Token en el header Authorization.
Ver docs
GET 📡 Lista Eventos de Ejemplos /ejemplos/eventos v1.0.0 📝 Descripción: Endpoint utilizado para obtener los eventos registrados de ejemplos (event sourcing). Soporta paginación por límite. 🔒 Autenticación: 🔑 Se requiere un token de autenticación válido como Bearer Token en el header Authorization. `` Authorization: Bearer <token> ``
Ver docs
GET 📤 Procesar Notificación Facturación /notificaciones/facturacion/{idStageNotificacionEstado} v1.0.0 Procesa un registro stage de notificación con destino facturación (invocado vía Cloud Tasks). Contrato: ProcesarNotificacionSapParamsSchema query forzar (true/false).
Ver docs
GET 📦 Consulta Paquetes Activos /paquetes v1.0.0 📝 Descripción: Endpoint utilizado para obtener los paquetes de guías anticipadas activos, filtrados por país, NIT del cliente y opcionalmente por división. 🔒 Autenticación: 🔑 Se requiere un token de autenticación válido como Bearer Token en el header Authorization. `` Authorization: Bearer <token> ``
Ver docs
GET 🔁 Reprocesar Notificaciones (Resiliencia) /notificaciones/resiliencia v1.0.0 Reencola notificaciones stage pendientes. Uso operativo (Cloud Scheduler / cuenta de servicio). Contrato query: ProcesarResilienciaQuerySchema (cantidad, default 500).
Ver docs
GET 🔁 Sincronizar Órdenes de Compra (Resiliencia) /ordenes-compras/sincronizar v1.0.0 Consulta OpenPay y actualiza el estado de órdenes pendientes de confirmación. Uso operativo (Cloud Scheduler / Cloud Tasks / cuenta de servicio). Contrato query: SincronizarOrdenesComprasQuerySchema en cm-guias-anticipadas-ms.
Ver docs
POST 🔍 Validar Estado de Pago /ordenes-compras/validar-pago v1.0.0 Consulta el estado actual de la orden asociada a una transacción OpenPay. Contrato: ValidarPagoBodySchema en cm-guias-anticipadas-ms.
Ver docs
POST 🔔 Webhook Estado de Transacción (OpenPay) /ordenes-compras/estado-transaccion v1.0.0 Recibe la notificación de OpenPay sobre cambios en la transacción. Contrato: EstadoTransaccionBodySchema en cm-guias-anticipadas-ms.
Ver docs
DELETE 🗑️ Vaciar Carrito /ordenes-compras v1.0.0 📝 Descripción: Elimina todas las líneas del carrito (estado = CARRITO) del cliente identificado por NIT y email. Contrato de entrada: VaciarCarritoBodySchema en cm-guias-anticipadas-ms.
Ver docs
GET 🛒 Lista Órdenes de Compra (Carrito) /ordenes-compras v1.0.0 📝 Descripción: Endpoint utilizado para listar las órdenes/carrito de paquetes filtradas por NIT, estado y email del cliente. 🔒 Autenticación: 🔑 Se requiere un token de autenticación válido como Bearer Token en el header Authorization. `` Authorization: Bearer <token> ``
Ver docs

Mostrando 19 de 19 endpoints