TPC API v1

API REST para integración empresarial directa con la plataforma TPC de mensajería y logística en Guatemala.

Base URL: https://api.tpcxpress.com/api/v1 · Todas las rutas requieren autenticación Bearer Token.

Quickstart en 3 pasos

Verifica tus credenciales

Confirma que tu token funciona correctamente consultando el perfil de tu empresa:

curl


curl https://api.tpcxpress.com/api/v1/empresa \
  -H "Authorization: Bearer TU_API_TOKEN"

JavaScript


const res = await fetch('https://api.tpcxpress.com/api/v1/empresa', {
  headers: { 'Authorization': `Bearer ${process.env.TPC_API_TOKEN}` },
})
const { data } = await res.json()
console.log(data.nombre)

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("/empresa").raise_for_status().json()["data"]
print(data["nombre"])

Respuesta esperada (200 OK):


{
  "success": true,
  "data": {
    "nombre": "Mi Empresa S.A.",
    "costoEntrega": 30.0,
    "tarifasPersonalizadas": []
  }
}

Si recibes 401 AUTH_REQUIRED → revisa que tu token sea correcto y esté en el header exacto Authorization: Bearer <token>.

Cotiza el envío (opcional)

Antes de crear una guía, puedes verificar el costo para un municipio específico:

curl


curl -X POST https://api.tpcxpress.com/api/v1/cotizar \
  -H "Authorization: Bearer TU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ciudadDestino": "Mixco" }'

JavaScript


const res = await fetch('https://api.tpcxpress.com/api/v1/cotizar', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.TPC_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ciudadDestino: 'Mixco' }),
})
const { data } = await res.json()
console.log(`Q ${data.costoFinal}`)

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.post("/cotizar", json={"ciudadDestino": "Mixco"}).raise_for_status().json()["data"]
print(f"Q {data['costoFinal']}")

Crea tu primera guía

curl


curl -X POST https://api.tpcxpress.com/api/v1/guias \
  -H "Authorization: Bearer TU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoServicio": "ESTANDAR",
    "ciudadDestino": "Mixco",
    "nombreDestinatario": "Juan Pérez",
    "telefonoDestinatario": "55551234",
    "direccionDestinatario": "3ra Avenida 5-10 zona 1"
  }'

JavaScript


const res = await fetch('https://api.tpcxpress.com/api/v1/guias', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.TPC_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tipoServicio: 'ESTANDAR',
    ciudadDestino: 'Mixco',
    nombreDestinatario: 'Juan Pérez',
    telefonoDestinatario: '55551234',
    direccionDestinatario: '3ra Avenida 5-10 zona 1',
  }),
})
const { data } = await res.json()
console.log(data.numeroGuia) // "TPCE123456789"

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.post("/guias", json={
    "tipoServicio": "ESTANDAR",
    "ciudadDestino": "Mixco",
    "nombreDestinatario": "Juan Pérez",
    "telefonoDestinatario": "55551234",
    "direccionDestinatario": "3ra Avenida 5-10 zona 1",
}).raise_for_status().json()["data"]
print(data["numeroGuia"])  # "TPCE123456789"

Respuesta (201 Created):


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

Guarda el numeroGuia — es tu referencia principal para consultar y hacer seguimiento.

Formato de respuestas

Todas las respuestas siguen el mismo envelope JSON:

Éxito


{
  "success": true,
  "data": { ... }
}

Error


{
  "success": false,
  "error": {
    "message": "Descripción legible del error",
    "code": "CODIGO_ERROR"
  }
}

Headers incluidos en toda respuesta


X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1751824200
X-Request-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479

Referencia de endpoints

Método	Ruta	Descripción
`GET`	`/empresa`	Perfil y tarifas de tu empresa
`GET`	`/municipios`	Lista de municipios con cobertura activa
`POST`	`/cotizar`	Calcular costo de envío antes de crear guía
`GET`	`/guias`	Listar guías con filtros y paginación
`POST`	`/guias`	Crear una guía
`POST`	`/guias/batch`	Crear hasta 50 guías en una operación atómica
`GET`	`/guias/{numeroGuia}`	Detalle completo de una guía
`PATCH`	`/guias/{numeroGuia}`	Editar datos del destinatario (solo en `SIN_RECOLLECTAR`)
`DELETE`	`/guias/{numeroGuia}`	Anular guía (solo en `SIN_RECOLLECTAR`)
`GET`	`/guias/{numeroGuia}/tracking`	Timeline completo de eventos
`GET`	`/guias/{numeroGuia}/pdf`	Descargar el PDF de la guía (binario)
`GET`	`/reportes`	Métricas y totales por período
`POST`	`/webhooks`	Registrar endpoint para notificaciones
`GET`	`/webhooks`	Listar webhooks activos
`GET`	`/webhooks/{id}`	Detalle y últimos 20 deliveries
`PATCH`	`/webhooks/{id}`	Actualizar URL, eventos o descripción
`DELETE`	`/webhooks/{id}`	Desactivar un webhook
`POST`	`/webhooks/{id}/test`	Enviar PING de prueba síncrono

Recursos rápidos

Cómo usar tu Bearer Token y prácticas de seguridad

Autenticación

Límites de requests y manejo de errores 429

Rate Limits

CRUD completo de guías de envío

Guías

Notificaciones en tiempo real de cambios de estado

Webhooks

Timeline de eventos de una guía

Tracking

Todos los códigos de error y estrategias de reintento

Catálogo de Errores

Ciclo de vida de una guía


Crear guía → SIN_RECOLLECTAR
                 ↓ (recolección por TPC)
             RECOLECTADO
                 ↓ (ingreso a bodega)
             EN_BODEGA
                 ↓ (asignación a mensajero)
             EN_RUTA
                 ↓                    ↓
           ENTREGADO            DEVOLUCION
                                    ↓
                           DEVOLUCION_ENTREGADO

   ANULADA ← (solo desde SIN_RECOLLECTAR)

SDKs y herramientas

La API es REST estándar — funciona con curl, fetch, axios, httpx o cualquier cliente HTTP. No hay SDK oficial por el momento.

¿Quieres probar sin afectar producción? Usa tu token tpc_test_… para el modo Sandbox — las guías se simulan, sin consumo de créditos ni escrituras en la base de datos.


// Ejemplo con fetch (Node.js / navegador)
const res = await fetch("https://api.tpcxpress.com/api/v1/guias", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TPC_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tipoServicio: "ESTANDAR",
    ciudadDestino: "Mixco",
    nombreDestinatario: "Juan Pérez",
    telefonoDestinatario: "55551234",
    direccionDestinatario: "3ra Avenida 5-10 zona 1",
  }),
});
 
const { data } = await res.json();
console.log(data.numeroGuia); // "TPCE123456789"