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)

GET/api/v1/guiasListar guías

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

Query params

Ejemplos

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

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

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

# 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/guiasCrear guía

Crea una nueva guía de envío. Si tu empresa es PREPAGO, consume 1 crédito, salvo que el destinatario pague el envío (COD_PRODUCTO_ENVIO, ENVIO_POR_COBRAR) o que el envío se descuente del cobro (COD_PRODUCTO con descontarEnvioDelCobro: true) — ver Créditos y Facturación.

Idempotency-Key (recomendado)

Si un request se corta por timeout no sabes si la guía se creó. Envía un header Idempotency-Key único por operación (por ejemplo un UUID que guardes junto a tu pedido) y reintenta con la misma clave:

Idempotency-Key: pedido-48213-2026-10-15

• El mismo request con la misma clave, dentro de 24 h, devuelve la respuesta original (header Idempotency-Replayed: true) sin crear ni cobrar otra guía.
• La misma clave con un body distinto → 409 IDEMPOTENCY_KEY_REUSED.
• Si el primero todavía se procesa → 409 IDEMPOTENCY_IN_PROGRESS; reintenta en unos segundos.
• Si el request falló (validación, sin créditos…) la clave queda libre: corrige y reintenta con ella.
• Es opcional: sin el header todo funciona como antes, pero un reintento puede duplicar la guía.

Body

Campos requeridos

Campos opcionales

Modalidad de cobro

modalidadCobro define exactamente qué cobra el mensajero al entregar. Es lo que se imprime en la etiqueta, así que determina cuánto efectivo se recoge en la puerta.

{
  "modalidadCobro": "COD_PRODUCTO_ENVIO",
  "costoProducto": 450.00,
  "ciudadDestino": "Mixco",
  "nombreDestinatario": "María López",
  "telefonoDestinatario": "5555-1234",
  "direccionDestinatario": "5a Avenida 10-20, Zona 1"
}

Compatibilidad. tipoServicio sigue funcionando: "ESTANDAR" equivale a PREPAGADO y "COD" a COD_PRODUCTO. Si mandas ambos, manda modalidadCobro. Las integraciones existentes no necesitan cambios.

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

Ejemplos

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"
  }'

curl -X POST https://api.tpcxpress.com/api/v1/guias \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoServicio": "COD",
    "ciudadDestino": "Villa Nueva",
    "nombreDestinatario": "Carlos López",
    "telefonoDestinatario": "55559876",
    "direccionDestinatario": "10ma Calle 5-66 zona 3",
    "costoProducto": 450.00,
    "obsDestinatario": "Cobrar exactamente Q450 al recibir"
  }'

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"
  }
}

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
    }
  }
}

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.

Body

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

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"
  }
}

El estado se vuelve a comprobar al guardar: si el mensajero recolecta la guía mientras tu request está en curso, responde el mismo 409 INVALID_STATE y no se aplica ningún cambio.

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",
    "creditoDevuelto": true
  }
}

creditoDevuelto es true cuando la guía había consumido un crédito (PREPAGO) y este volvió a tu saldo.

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? Si la guía consumió un crédito (PREPAGO), el crédito vuelve a tu saldo en el momento de anularla, en la misma operación. Las guías POSTPAGO o en las que el destinatario paga el envío no consumen crédito, así que no hay nada que devolver.

¿Puedo cambiar la modalidad de cobro de una guía ya creada? No. La modalidad (y tipoServicio) son inmutables una vez creada la guía. Anula y crea una nueva si necesitas cambiarla.

Si cambio ciudadDestino con PATCH, ¿cambia el precio? Sí. Al cambiar el destino se recalcula costoServicio con la tarifa del municipio nuevo, y si el destinatario paga el envío (COD_PRODUCTO_ENVIO o ENVIO_POR_COBRAR) también se ajusta el monto que cobra el mensajero. Si el municipio nuevo no tiene cobertura, el PATCH se rechaza con 422 MUNICIPIO_NO_CUBIERTO y la guía queda intacta.

¿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 422 MUNICIPIO_NO_CUBIERTO.