Autenticación

La API usa Bearer Token en cada request. Todas las rutas (excepto rutas internas) requieren autenticación.

Cómo autenticarte

Incluye tu token en el header Authorization de cada request:


Authorization: Bearer TU_API_TOKEN

Ejemplo con curl


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

Ejemplo con JavaScript (fetch)


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

Ejemplo con Python (httpx)


import httpx
import os
 
client = httpx.Client(
    base_url="https://api.tpcxpress.com/api/v1",
    headers={"Authorization": f"Bearer {os.environ['TPC_API_TOKEN']}"},
)
response = client.get("/empresa")

Obtener tu token

Accede al portal de integraciones

Inicia sesión en tu cuenta del portal TPC y ve a la sección Integraciones.

Si tu empresa aún no está verificada, primero completa el proceso de verificación desde Perfil → Mi empresa.

Genera tus tokens de API

Haz clic en Generar tokens. Se crean simultáneamente dos tokens:

Token	Prefijo	Uso
Live	`tpc_live_…`	Producción — crea guías reales y consume créditos
Test	`tpc_test_…`	Sandbox — simula respuestas sin afectar datos ni créditos

Ambos tokens se muestran solo una vez — cópialos inmediatamente.

Para sucursales: la cuenta Matriz puede generar tokens individuales por sucursal desde la pestaña de cada sucursal en Integraciones.

Guárdalo de forma segura

Nunca escribas el token directamente en tu código. Úsalo siempre como variable de entorno:


# .env.local (no commitear)
TPC_API_TOKEN=tpc_live_xxxxxxxxxxxxxxxx


# Vercel / Railway / Render / Heroku
vercel env add TPC_API_TOKEN production

Tokens de sucursal

Si tu empresa tiene sucursales habilitadas, cada sucursal puede tener su propio token de API independiente del token principal de la empresa.

¿Para qué sirven?

Un token de sucursal permite que cada sucursal opere de forma aislada:

Las guías creadas con un token de sucursal quedan asociadas a esa sucursal
Al listar guías (GET /guias) solo se retornan las guías de esa sucursal
Los webhooks configurados para la sucursal reciben sus propios eventos

Gestión desde el portal

Solo la cuenta Matriz puede generar, regenerar y eliminar tokens de sucursal. Ve a Integraciones en el portal y selecciona la pestaña de la sucursal correspondiente.

Comportamiento por tipo de token

Token	Guías visibles	Webhooks que reciben eventos
Empresa (Matriz)	Todas las guías de la empresa	Solo webhooks sin sucursal asignada
Sucursal	Solo guías de esa sucursal	Webhooks de la empresa + webhooks de esa sucursal

Cómo funciona internamente

El token se valida así en cada request:

El servidor extrae el valor del header Authorization: Bearer <token>
Calcula SHA-256(token) y busca en Redis (caché de 60 segundos)
Si no está en caché, busca el hash en las columnas apiTokenHash y apiTokenTestHash de empresa/sucursal
Si coincide con un token live → modo producción; si coincide con un token test → modo sandbox
El resultado (incluido el modo) se cachea por 60 segundos usando el hash como clave

Al rotar o eliminar un token desde el portal, la caché de Redis se invalida inmediatamente. El token anterior deja de funcionar de forma instantánea.

Errores de autenticación

HTTP	Código	Causa
`401`	`AUTH_REQUIRED`	Header `Authorization` ausente
`401`	`AUTH_REQUIRED`	Formato incorrecto (falta `Bearer` )
`401`	`AUTH_REQUIRED`	Token inválido o no existe en el sistema


{
  "success": false,
  "error": {
    "message": "Token de autenticación requerido.",
    "code": "AUTH_REQUIRED"
  }
}

Buenas prácticas

Nunca expongas tu token en código del lado del cliente, repositorios públicos, logs, o respuestas de API.

Almacena el token exclusivamente como variable de entorno
Rota el token inmediatamente si sospechas que fue comprometido — usa Regenerar en el portal; el token anterior se invalida de forma instantánea
Para sistemas con múltiples sucursales, usa el token de sucursal correspondiente en cada integración
En sistemas CI/CD, usa los secret managers del proveedor (GitHub Secrets, Vercel Env, AWS Secrets Manager)