Autenticación ​

Todas las peticiones a la API Masivo requieren una API Key. La llave se envía en el header Authorization con el esquema Bearer:

Authorization: Bearer tmb_test_tu_api_key_aqui

No se aceptan llaves en el cuerpo de la petición ni en la query string.

Crear una API Key ​

1. Inicia sesión en el panel de Timbra.
2. Entra a la sección API Keys.
3. Pulsa Crear API Key.
4. Escribe un nombre que te ayude a identificar el sistema o la integración.
5. Elige el entorno:
   • Producción (Live) para emitir CFDI reales ante el SAT.
   • Pruebas (Test / Sandbox) para integrar y probar sin costo.
6. Copia la llave y guárdala en un lugar seguro.

Tipos de llave ​

El tipo de llave determina el comportamiento de la API. No necesitas cambiar la URL ni enviar un parámetro adicional.

Consulta Ambientes Live y Test para ver los RFCs de prueba y las diferencias completas.

Ejemplo de petición autenticada ​

curl -X POST "https://dashboard.timbra.com.mx/api/masivo/v3/cfdi33/issue/json/v4" \
  -H "Authorization: Bearer tmb_test_tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d @cfdi.json

const response = await fetch(
  'https://dashboard.timbra.com.mx/api/masivo/v3/cfdi33/issue/json/v4',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TIMBRA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(cfdi)
  }
)

const result = await response.json()
console.log(result.data.uuid)

import os
import requests

response = requests.post(
    "https://dashboard.timbra.com.mx/api/masivo/v3/cfdi33/issue/json/v4",
    headers={
        "Authorization": f"Bearer {os.environ['TIMBRA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=cfdi,
)

result = response.json()
print(result["data"]["uuid"])

Errores de autenticación ​

Si falta el header o el formato es incorrecto, la API responde con HTTP 401:

{
  "status": "error",
  "message": "Token de autenticación faltante o formato inválido. Use Authorization: Bearer <API_KEY>"
}

Si la llave no existe o fue revocada, la respuesta es:

{
  "status": "error",
  "message": "API Key inválida o inactiva."
}

Buenas prácticas ​

• No expongas la llave en el frontend. Úsala solo desde tu servidor o desde un backend intermedio.
• Guárdala en variables de entorno o en un gestor de secretos, nunca en el repositorio.
• Usa una llave por integración. Así puedes revocar una sin afectar a las demás.
• Rota la llave si sospechas que se filtró: revócala y crea una nueva.
• No uses llaves Live en pruebas. Una prueba con una llave Live consume timbres reales.

Límites de peticiones (Rate Limiting) ​

Para proteger la infraestructura y garantizar alta disponibilidad, las peticiones a la API Masivo están sujetas a un límite de tasa (rate limit) evaluado por cada API Key:

Encabezados de control ​

Cada respuesta de la API incluye encabezados estándar con el estado de tu cuota:

• RateLimit-Limit: Cantidad total de peticiones permitidas en la ventana actual.
• RateLimit-Remaining: Peticiones restantes en la ventana actual.
• RateLimit-Reset: Tiempo restante en segundos para el reinicio de la ventana.

Si excedes el límite, la API responderá con un código HTTP 429 Too Many Requests:

{
  "status": "error",
  "message": "Demasiadas peticiones. Ha excedido el límite de 1000 peticiones por ventana de 15 minutos para esta API Key."
}

Revocar una API Key ​

Desde la misma sección API Keys del panel puedes revocar cualquier llave. La revocación es inmediata: cualquier sistema que la esté usando recibirá 401 en su siguiente petición.

Para probar sin riesgo, crea una llave tmb_test_... y usa los RFCs de prueba del SAT. Consulta la guía de Ambientes.