Consultar estado actual de guías (múltiples)

Obtiene el estado actual e información del último evento para una o más guías.

GET /public/guias/estados/actual v1.0.0
Autenticación
Bearer Token, API Key
Ambiente
Servidor de Desarrollo, Servidor de Producción

Descripción

Obtiene el estado actual e información del último evento para una o más guías. Retorna estado actual, macroestado y detalles del evento.

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

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

Ejemplo rápido

Generando ejemplo…

Endpoint

GET /public/guias/estados/actual

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
{
    "isError": false,
    "message": "Consulta procesada correctamente",
    "data": {
        "procesadas": 1,
        "guias": [
            {
                "numero_guia": "99925237145301",
                "estado_actual": "Guía ingresada en ruta de reparto",
                "id_estado_actual": 7,
                "macroestado_actual": "En tránsito",
                "id_macroestado_actual": 2,
                "evento": {
                    "fecha_hora_evento_utc": "2026-01-30T18:45:00.000Z",
                    "fecha_hora_evento_zona_horaria": "2026-01-30T13:45:00",
                    "codigo_iana": "America/Bogota",
                    "codigo_iso_alpha3": "COL",
                    "nombre_poblacion": "BOGOTÁ D.C.",
                    "terminal_checkpoint": 1,
                    "id_checkpoint": 123456
                }
            }
        ]
    },
    "timestamp": "2026-01-30T18:45:10.000Z"
}

Ejemplo de respuesta

200 Consulta exitosa 
{
    "isError": false,
    "message": "Consulta procesada correctamente",
    "data": {
        "procesadas": 1,
        "guias": [
            {
                "numero_guia": "99925237145301",
                "estado_actual": "Guía ingresada en ruta de reparto",
                "id_estado_actual": 7,
                "macroestado_actual": "En tránsito",
                "id_macroestado_actual": 2,
                "evento": {
                    "fecha_hora_evento_utc": "2026-01-30T18:45:00.000Z",
                    "fecha_hora_evento_zona_horaria": "2026-01-30T13:45:00",
                    "codigo_iana": "America/Bogota",
                    "codigo_iso_alpha3": "COL",
                    "nombre_poblacion": "BOGOTÁ D.C.",
                    "terminal_checkpoint": 1,
                    "id_checkpoint": 123456
                }
            }
        ]
    },
    "timestamp": "2026-01-30T18:45:10.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 del servidor
{
    "isError": true,
    "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "Error al consultar estados",
        "details": "Database connection timeout"
    },
    "timestamp": "2026-01-30T20:15:00.000Z"
}