Tracking — Seguimiento de guías

GET`/api/v1/guias/{numeroGuia}/tracking`

Retorna el timeline completo de eventos de una guía, ordenado cronológicamente. Combina eventos del sistema (estados) con intentos de entrega fallidos en una sola línea de tiempo unificada.

Alcance. Con un token de sucursal solo se puede consultar una guía de esa sucursal; cualquier otra responde 404 NOT_FOUND, igual que en el resto de endpoints. Ver tokens de sucursal.

Ejemplo

curl


curl https://api.tpcxpress.com/api/v1/guias/TPCP123456789/tracking \
  -H "Authorization: Bearer TOKEN"

JavaScript


const res = await fetch(
  'https://api.tpcxpress.com/api/v1/guias/TPCP123456789/tracking',
  { headers: { 'Authorization': `Bearer ${process.env.TPC_API_TOKEN}` } },
)
const { data } = await res.json()
// data.estadoActual, data.timeline

Python


import httpx, os
 
client = httpx.Client(
    base_url="https://api.tpcxpress.com/api/v1",
    headers={"Authorization": f"Bearer {os.environ['TPC_API_TOKEN']}"},
)
data = client.get("/guias/TPCP123456789/tracking").raise_for_status().json()["data"]
# data["estadoActual"], data["timeline"]

Respuesta 200


{
  "success": true,
  "data": {
    "numeroGuia": "TPCP123456789",
    "estadoActual": "ENTREGADO",
    "totalEventos": 5,
    "timeline": [
      {
        "tipo": "IMPORTADA",
        "descripcion": "Guía creada via API.",
        "timestamp": "2026-07-06T08:00:00.000Z"
      },
      {
        "tipo": "RECOLECTADA",
        "descripcion": "Recolectada en sesión de recolección.",
        "timestamp": "2026-07-06T09:30:00.000Z"
      },
      {
        "tipo": "ASIGNADA",
        "descripcion": "Asignada a mensajero para despacho.",
        "timestamp": "2026-07-06T11:00:00.000Z"
      },
      {
        "tipo": "INTENTO_FALLIDO",
        "descripcion": "Destinatario ausente, no responde.",
        "timestamp": "2026-07-06T14:00:00.000Z",
        "fotoUrl": null
      },
      {
        "tipo": "ENTREGA_EXITOSA",
        "descripcion": "Entrega completada.",
        "timestamp": "2026-07-07T10:00:00.000Z",
        "fotoUrl": "https://storage.tpc.gt/entregas/prueba-123.jpg"
      }
    ]
  }
}

Estructura del timeline

Cada evento en el timeline tiene la siguiente estructura:

Campo	Tipo	Descripción
`tipo`	string	Tipo de evento (ver tabla abajo)
`descripcion`	string	Descripción legible del evento
`timestamp`	ISO 8601	Fecha y hora exacta del evento (UTC)
`fotoUrl`	string \| null	Enlace firmado a la foto del intento, válido 15 minutos (vuelve a consultar el tracking para obtener uno nuevo). `null` si no hay foto

Tipos de eventos

Tipo	Origen	Descripción
`IMPORTADA`	Sistema	Guía creada (via API o importación masiva)
`RECOLECTADA`	Mensajero / Admin	Recolectada en la dirección del cliente
`INGRESO_BODEGA`	Admin	Ingresó a bodega TPC (estado `EN_BODEGA`), lista para organizar en ruta
`ASIGNADA`	Admin	Asignada a mensajero para despacho
`ENTREGA_EXITOSA`	Mensajero	Entregada exitosamente al destinatario
`INTENTO_FALLIDO`	Mensajero	Intento sin éxito (puede haber foto)
`DEVUELTA`	Admin	Proceso de devolución iniciado
`ANULADA`	API / Admin	Guía cancelada antes de recolección

Los eventos INTENTO_FALLIDO pueden incluir una fotoUrl con evidencia del intento. Los eventos de ENTREGA_EXITOSA incluyen foto de comprobante cuando el mensajero la registra.

Ciclo de vida completo


Creación
   │
   ▼
IMPORTADA ──────────────────────────────────── ANULADA
   │                                          (solo aquí)
   ▼
RECOLECTADA
   │
   ▼
INGRESO_BODEGA
   │
   ▼
ASIGNADA
   │
   ├─ INTENTO_FALLIDO ──┐
   │                    │ (reintento)
   │  ◄─────────────────┘
   │
   ├──► ENTREGA_EXITOSA
   │
   └──► DEVUELTA

Polling vs. Webhooks

El endpoint de tracking es ideal para mostrar el estado actual en tu UI. Sin embargo, para reaccionar a cambios en tiempo real (actualizar tu sistema, notificar al cliente), usa Webhooks en lugar de hacer polling periódico.

	Tracking polling	Webhooks
Latencia	Depende del intervalo	Segundos tras el evento
Costo de requests	Según frecuencia	1 request por evento
Implementación	Simple	Requiere endpoint receptor
Mejor para	UI de consulta del cliente	Automatización del sistema