Guías

Una guía es el documento central del flujo logístico de TPC. Representa un envío desde que se crea hasta que es entregado o devuelto.

Estados de una guía


SIN_RECOLLECTAR → RECOLECTADO → EN_BODEGA → EN_RUTA → ENTREGADO
                                                      ↘ DEVOLUCION → DEVOLUCION_ENTREGADO
                                                      ↘ SINIESTRO (robo/extravío)
                                                      ↘ DANADA (dañada en tránsito)
                   ANULADA ← (solo desde SIN_RECOLLECTAR)
                                              ENTREGADO_LIQUIDADO (post-liquidación)

Estado	Descripción
`SIN_RECOLLECTAR`	Guía creada, pendiente de recolección
`RECOLECTADO`	Recolectada en bodega del cliente
`EN_BODEGA`	En bodega TPC, clasificando para despacho
`EN_RUTA`	Asignada a mensajero, en camino al destinatario
`ENTREGADO`	Entregada exitosamente al destinatario
`DEVOLUCION`	En proceso de devolución al remitente
`DEVOLUCION_ENTREGADO`	Devuelta y entregada al remitente
`ANULADA`	Cancelada (solo posible en `SIN_RECOLLECTAR`)
`ENTREGADO_LIQUIDADO`	Entregada y liquidada contablemente
`SINIESTRO`	Robada o extraviada — reclamo de seguro abierto (ver módulo Reclamos)
`DANADA`	Dañada en tránsito, nunca llegó a destino — reclamo de seguro abierto

Una guía que se dañó después de ser entregada conserva su estado ENTREGADO/ENTREGADO_LIQUIDADO — DANADA solo aplica cuando el paquete nunca llegó a su destino. El flete se sigue facturando normalmente en ambos casos; el reclamo de seguro cubre el valor de la mercadería, por separado.

GET`/api/v1/guias`Listar guías

Lista todas las guías de tu empresa con soporte de filtros y paginación.

Query params

Parámetro	Tipo	Default	Descripción
`estado`	string	—	Filtrar por estado (ver tabla de estados)
`fechaDesde`	`YYYY-MM-DD`	—	Guías creadas desde esta fecha (inclusive)
`fechaHasta`	`YYYY-MM-DD`	—	Guías creadas hasta esta fecha (inclusive, hasta las 23:59:59 hora Guatemala)
`page`	integer	`1`	Número de página
`limit`	integer	`20`	Resultados por página (máximo `100`)

Ejemplos

Todas las guías


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

Filtrar por estado


curl "https://api.tpcxpress.com/api/v1/guias?estado=EN_RUTA" \
  -H "Authorization: Bearer TOKEN"

Filtrar por fecha


curl "https://api.tpcxpress.com/api/v1/guias?fechaDesde=2026-07-01&fechaHasta=2026-07-06" \
  -H "Authorization: Bearer TOKEN"

Paginación


# Página 2, 50 resultados por página
curl "https://api.tpcxpress.com/api/v1/guias?page=2&limit=50" \
  -H "Authorization: Bearer TOKEN"

Respuesta 200


{
  "success": true,
  "data": {
    "guias": [
      {
        "id": "cluuid123",
        "numeroGuia": "TPCP123456789",
        "estado": "EN_RUTA",
        "esCOD": false,
        "montoTotal": null,
        "direccionEntrega": "8va Avenida 12-34 zona 11",
        "municipioDestino": "Mixco",
        "destinatario": {
          "nombre": "Juan Pérez",
          "telefono": "55551234",
          "ciudad": "Mixco"
        },
        "tipoServicio": "ESTANDAR",
        "costoServicio": 30.00,
        "createdAt": "2026-07-06T14:00:00.000Z",
        "fechaEntrega": null
      }
    ],
    "meta": {
      "total": 150,
      "page": 1,
      "limit": 20,
      "totalPages": 8
    }
  }
}

POST`/api/v1/guias`Crear guía

Crea una nueva guía de envío. Consume 1 crédito si tu empresa no tiene plan APROBADA.

Body

Campos requeridos

Campo	Tipo	Descripción
`tipoServicio`	`"ESTANDAR"` \| `"COD"`	Tipo de servicio de envío
`ciudadDestino`	string (2–100 chars)	Municipio de destino
`nombreDestinatario`	string (2–150 chars)	Nombre completo de quien recibe
`telefonoDestinatario`	string (7–30 chars)	Teléfono de contacto del destinatario
`direccionDestinatario`	string (5–300 chars)	Dirección completa de entrega

Campos opcionales

Campo	Tipo	Descripción
`costoProducto`	number (positivo)	Requerido si `tipoServicio = "COD"`. Valor del producto a cobrar al destinatario
`correoDestinatario`	string (email)	Correo electrónico del destinatario
`obsDestinatario`	string (máx 500)	Instrucciones especiales de entrega
`telefonoAlternoDestinatario`	string (máx 30)	Teléfono alternativo del destinatario
`fechaRecoleccion`	`YYYY-MM-DD`	Fecha preferida de recolección. Se interpreta como medianoche en hora de Guatemala (UTC-6).

Datos del remitente — se toman automáticamente de la configuración de tu empresa (nombre, teléfono, ciudad de origen).

Ejemplos

Servicio Estándar


curl -X POST https://api.tpcxpress.com/api/v1/guias \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoServicio": "ESTANDAR",
    "ciudadDestino": "Mixco",
    "nombreDestinatario": "Ana García",
    "telefonoDestinatario": "55554321",
    "direccionDestinatario": "8va Avenida 12-34 zona 11",
    "obsDestinatario": "Llamar 30 min antes de llegar"
  }'

Respuesta 201


{
  "success": true,
  "data": {
    "numeroGuia": "TPCE123456789",
    "estado": "SIN_RECOLLECTAR",
    "pdfUrl": "https://api.tpcxpress.com/api/v1/guias/TPCE123456789/pdf",
    "createdAt": "2026-07-06T14:30:00.000Z"
  }
}

El campo pdfUrl apunta al endpoint público de descarga. Requiere tu token en el header Authorization. Ver PDF de guía.

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

Retorna el detalle completo de una guía, incluyendo datos del destinatario, servicio y todos los timestamps relevantes.


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

Respuesta 200


{
  "success": true,
  "data": {
    "id": "cluuid123",
    "numeroGuia": "TPCP123456789",
    "estado": "EN_RUTA",
    "pdfUrl": "https://api.tpcxpress.com/api/v1/guias/TPCP123456789/pdf",
    "esCOD": false,
    "montoTotal": null,
    "municipioDestino": "Mixco",
    "destinatario": {
      "nombre": "Ana García",
      "correo": "ana@example.com",
      "telefono": "55554321",
      "direccion": "8va Avenida 12-34 zona 11",
      "ciudad": "Mixco",
      "observaciones": "Llamar 30 min antes de llegar"
    },
    "servicio": {
      "tipo": "ESTANDAR",
      "costoEnvio": 30.00,
      "costoProducto": null,
      "cantidadPaquetes": "1"
    },
    "timestamps": {
      "createdAt": "2026-07-06T14:00:00.000Z",
      "recolectadoEn": "2026-07-06T09:00:00.000Z",
      "asignadoEn": "2026-07-06T10:30:00.000Z",
      "fechaProgramada": null,
      "fechaEntrega": null
    }
  }
}

Campo	Descripción
`pdfUrl`	URL del PDF de la guía — requiere token en `Authorization`
`esCOD`	`true` si es servicio Cobro Contra Entrega
`montoTotal`	Monto a cobrar al destinatario (solo COD)
`servicio.costoEnvio`	Costo del servicio de mensajería (lo que paga la empresa)
`timestamps.recolectadoEn`	Cuando TPC recolectó el paquete
`timestamps.asignadoEn`	Cuando se asignó a un mensajero
`timestamps.fechaEntrega`	Cuando se completó la entrega (null si no entregada)

PATCH`/api/v1/guias/{numeroGuia}`Editar guía

Edita los datos del destinatario o dirección de una guía. Solo es posible mientras la guía está en estado SIN_RECOLLECTAR.

Una vez que TPC recolecta la guía (estado RECOLECTADO o posterior), los datos del destinatario no pueden modificarse via API. Contacta a soporte para correcciones urgentes.

Body

Al menos un campo es requerido. Solo se actualizan los campos enviados.

Campo	Tipo	Descripción
`nombreDestinatario`	string (2–150)	Nombre del destinatario
`telefonoDestinatario`	string (7–30)	Teléfono principal
`telefonoAlternoDestinatario`	string (máx 30) \| null	Teléfono alternativo
`correoDestinatario`	string (email) \| `""`	Correo del destinatario
`direccionDestinatario`	string (5–300)	Dirección de entrega
`ciudadDestino`	string (2–100)	Municipio de destino
`obsDestinatario`	string (máx 500) \| null	Instrucciones de entrega

Ejemplo


# Corregir dirección y agregar teléfono alterno
curl -X PATCH https://api.tpcxpress.com/api/v1/guias/TPCE123456789 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "direccionDestinatario": "8va Avenida 15-20 zona 11, apto 3B",
    "telefonoAlternoDestinatario": "44448888",
    "obsDestinatario": "Portón azul, timbre 3B"
  }'

Respuesta 200

Retorna el objeto guía completo con los datos actualizados (mismo formato que GET /guias/{numeroGuia}).

Errores específicos


{
  "success": false,
  "error": {
    "message": "No se puede editar una guía con estado \"RECOLECTADO\". Solo es posible editar guías en estado SIN_RECOLLECTAR.",
    "code": "INVALID_STATE"
  }
}

DELETE`/api/v1/guias/{numeroGuia}`Anular

Anula una guía. Solo es posible en estado SIN_RECOLLECTAR.

La anulación es irreversible — la guía pasa a estado ANULADA permanentemente y no puede reactivarse.


curl -X DELETE https://api.tpcxpress.com/api/v1/guias/TPCE123456789 \
  -H "Authorization: Bearer TOKEN"

Respuesta 200


{
  "success": true,
  "data": {
    "numeroGuia": "TPCE123456789",
    "estado": "ANULADA"
  }
}

Error 409 Estado inválido


{
  "success": false,
  "error": {
    "message": "No se puede anular una guía con estado \"EN_RUTA\". Solo es posible anular guías en estado SIN_RECOLLECTAR.",
    "code": "INVALID_STATE"
  }
}

Preguntas frecuentes

¿Qué pasa con los créditos si anulo una guía? Los créditos no se reembolsan automáticamente al anular. Contacta a soporte para casos específicos.

¿Puedo cambiar el tipoServicio de ESTANDAR a COD? No. El tipo de servicio es inmutable una vez creada la guía. Anula y crea una nueva si necesitas cambiarlo.

¿Cómo sé si el municipio de destino tiene cobertura? Consulta GET /api/v1/municipios para ver la lista de municipios activos. Si el municipio no tiene cobertura, la API rechazará la creación con 400 MUNICIPIO_NO_CUBIERTO.

Guías

Estados de una guía

GET/api/v1/guiasListar guías

Query params

Ejemplos

Todas las guías

Filtrar por estado

Filtrar por fecha

Paginación

Respuesta 200

POST/api/v1/guiasCrear guía

Body

Campos requeridos

Campos opcionales

Ejemplos

Servicio Estándar

Servicio COD

Respuesta 201

GET/api/v1/guias/{numeroGuia}Detalle

Respuesta 200

PATCH/api/v1/guias/{numeroGuia}Editar guía

Body

Ejemplo

Respuesta 200

Errores específicos

DELETE/api/v1/guias/{numeroGuia}Anular

Respuesta 200

Error 409 Estado inválido

Preguntas frecuentes

GET`/api/v1/guias`Listar guías

POST`/api/v1/guias`Crear guía

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

PATCH`/api/v1/guias/{numeroGuia}`Editar guía

DELETE`/api/v1/guias/{numeroGuia}`Anular