Consultar histórico de estados de guías

Descripción

Retorna el histórico de eventos de estado para hasta 20 guías, incluyendo un resumen del estado y macroestado actual de cada guía y la lista de eventos ordenada descendentemente por fecha UTC. Cada evento incluye la fecha en UTC y convertida a la zona horaria local de la terminal del checkpoint (fallback a UTC cuando la terminal es desconocida).

Reglas de validación de guías

Se aceptan hasta *20 guías* por consulta (separadas por coma).
Cada guía debe tener exactamente *11 dígitos numéricos*.
Las guías duplicadas se deduplican.
Las guías inválidas (longitud ≠ 11 o con caracteres no numéricos) se

*descartan silenciosamente* — no generan error HTTP, solo se registran en logs (LONGITUD_INCORRECTA, CARACTERES_INVALIDOS).

Quick Start

Obtén tus credenciales de acceso (Bearer Token, API Key).
Selecciona el ambiente y completa los parámetros requeridos.
Envía la solicitud y procesa la respuesta.

Ejemplo rápido

Generando ejemplo…

Generando ejemplo…

Generando ejemplo…

Endpoint

GET /public/estado-guia/v1/historico

Base URL https://api-dev.coordinadora.tech/mio

Parámetros

Nombre	Tipo	Requerido	Descripción
`guias` query	string	Sí	Números de guía separados por coma. Máximo 20 guías; cada guía debe tener exactamente 11 dígitos numéricos. Las guías inválidas se descartan sin generar error.

Headers

Header	Tipo	Requerido	Descripción
`x-client-id`	string	Sí	Identificador del cliente consumidor.
`x-app-sources`	string	Sí	Aplicación origen de la petición.
`x-timestamp`	string	Sí	Marca de tiempo de la petición (ISO 8601).
`x-request`	string	Sí	Identificador único de la petición para trazabilidad.

Respuesta

200

Consulta exitosa. Si ninguna guía válida tiene información, data.procesadas es 0, data.guias es [] y se incluye el campo message.

{
    "isError": false,
    "data": {
        "procesadas": 1,
        "guias": [
            {
                "numero_guia": "73941445369",
                "resumen": {
                    "estado_actual": "Abierto",
                    "id_estado_actual": 2,
                    "macroestado_actual": "En tránsito",
                    "id_macroestado_actual": 3
                },
                "eventos": [
                    {
                        "fecha_hora_evento_utc": "2026-05-19T22:31:39.915Z",
                        "fecha_hora_evento_zona_horaria": "2026-05-19T17:31:39.915-05:00",
                        "codigo_iana": "America/Bogota",
                        "nombre_poblacion": "Bogotá",
                        "codigo_iso_alpha3": "COL",
                        "terminal_checkpoint": 1,
                        "id_estado_guia": 2,
                        "nombre_estado_guia": "Abierto",
                        "id_checkpoint": 100
                    }
                ]
            }
        ]
    },
    "timestamp": "2026-05-19T22:31:40.000Z"
}

Ejemplo de respuesta

200 Consulta exitosa. Si ninguna guía válida tiene información, data.procesadas es 0, data.guias es [] y se incluye el campo message.

{
    "isError": false,
    "data": {
        "procesadas": 1,
        "guias": [
            {
                "numero_guia": "73941445369",
                "resumen": {
                    "estado_actual": "Abierto",
                    "id_estado_actual": 2,
                    "macroestado_actual": "En tránsito",
                    "id_macroestado_actual": 3
                },
                "eventos": [
                    {
                        "fecha_hora_evento_utc": "2026-05-19T22:31:39.915Z",
                        "fecha_hora_evento_zona_horaria": "2026-05-19T17:31:39.915-05:00",
                        "codigo_iana": "America/Bogota",
                        "nombre_poblacion": "Bogotá",
                        "codigo_iso_alpha3": "COL",
                        "terminal_checkpoint": 1,
                        "id_estado_guia": 2,
                        "nombre_estado_guia": "Abierto",
                        "id_checkpoint": 100
                    }
                ]
            }
        ]
    },
    "timestamp": "2026-05-19T22:31:40.000Z"
}

Errores

400

Error de validación de esquema (SCHEMA_VALIDATION_ERROR): falta el parámetro guias, se enviaron más de 20 guías, o falta algún header requerido.

{
    "isError": true,
    "message": "Se requiere guias",
    "code": "SCHEMA_VALIDATION_ERROR",
    "cause": "ValidationError",
    "statusCode": 400,
    "id": "3f9c1a2b4d5e6f708192a3b4c5d6e7f801234567"
}

500

Error interno (REPOSITORY_ERROR por fallo en PostgreSQL/Redis, GOT_ERROR por fallo en el API de Proveedor Datos Maestros, o UNKNOWN_ERROR).

{
    "isError": true,
    "message": "Error consultando el histórico de estados",
    "code": "REPOSITORY_ERROR",
    "cause": "connection refused",
    "statusCode": 500,
    "id": "3f9c1a2b4d5e6f708192a3b4c5d6e7f801234567"
}