Autenticación y ambientes de la API
Cómo autenticarte con el header X-Api-Key, la diferencia entre sandbox y producción, los límites por minuto y cómo proteger tu API key.
La API de TimbraMX se autentica con un header X-Api-Key en cada petición. Cada cuenta tiene dos keys, generadas desde la vista “API” del portal: una de sandbox y una de producción. La URL es siempre la misma, https://app.timbra-mx.com/api/v1; el servidor decide el ambiente según contra cuál de las dos keys coincide el header.
curl
curl https://app.timbra-mx.com/api/v1/facturas/saldo -H "X-Api-Key: TU_API_KEY"Sandbox contra producción
| Característica | Sandbox | Producción |
|---|---|---|
| Timbra de verdad contra el PAC | Sí (ambiente de pruebas) | Sí (ambiente de producción) |
| UUID | Real, generado por el PAC de pruebas | Real, con valor fiscal |
| Valor fiscal ante el SAT | No | Sí |
| Consume timbres de tu saldo | No, nunca | Sí, 1 por timbrado exitoso |
| Requiere certificación previa | No | Sí: contacta a soporte |
| Cómo se obtiene la key | Se genera libre desde el portal | Solo se genera si la cuenta está certificada |
| Vigencia de la key | 90 días de inactividad; se renueva al regenerarla | No expira por inactividad |
El sandbox no es una simulación local: aplica las mismas validaciones y reglas de negocio, y puedes probar la cancelación de punta a punta e incluso provocar errores reales del PAC para probar cómo los manejas antes de ir a producción. El saldo que ves en GET /facturas/saldo es siempre el real de producción, sin importar con cuál key lo consultes.
Del sandbox a producción
- Integra y prueba con tu key de sandbox.
- Cuando funcione bien, contacta a soporte para certificar tu cuenta.
- Genera tu API key de producción desde el portal y cámbiala en tu integración. La URL no cambia.
Límites
- 60 peticiones por minuto, por recurso. Facturas, Complementos de pago, Nómina y Retenciones tienen cada uno su propio contador; no es una sola bolsa por cuenta. El límite es por cuenta autenticada, no por IP.
- Las respuestas traen los headers
RateLimit-Limit,RateLimit-RemainingyRateLimit-Reset(segundos restantes de la ventana). No hay headerRetry-After. - 10 MB máximo por petición y 30 segundos de timeout recomendado en tu cliente.
- Si procesas lotes, deja al menos 1.5 segundos entre peticiones consecutivas desde el mismo servidor: existe una protección anti-bot más estricta que el límite normal, y puede bloquear la IP si llegan ráfagas de 4 peticiones en 5 segundos, incluso con una key válida.
Cómo cuidar tu API key
- Úsala solo desde tu backend; nunca en navegador ni apps móviles.
- No la subas a un repositorio. Guárdala en variables de entorno o en el manejo de secretos de tu infraestructura.
- No la registres en logs: si tu sistema guarda headers completos, excluye
X-Api-Key. - Si se compromete, regénerala de inmediato desde el portal; la anterior deja de funcionar al instante.
Preguntas frecuentes
¿Cómo obtengo mi API key?
Desde la vista “API” del portal. La de sandbox se genera al instante y sin aprobación; la de producción solo después de certificar tu cuenta con soporte.
¿La URL cambia entre sandbox y producción?
No. Es siempre https://app.timbra-mx.com/api/v1; el ambiente lo determina la API key.
¿El sandbox consume timbres?
No. Nunca consume tu saldo y sus comprobantes no tienen valor fiscal.
¿Qué pasa si mi key de sandbox expira?
Vence tras 90 días de inactividad. Se renueva regenerándola desde el portal.
¿Listo para integrar?
Crea tu cuenta gratis, genera tu API key de sandbox y prueba el timbrado de punta a punta sin consumir timbres.
Crear cuenta gratis Ver precios de la APIDocumentación de la API de TimbraMX, versión v1. Actualizada el 27 de octubre de 2026. Todos los ejemplos usan claves de ejemplo: nunca publiques tu API key real.