Documentación de la API · v1

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ísticaSandboxProducción
Timbra de verdad contra el PACSí (ambiente de pruebas)Sí (ambiente de producción)
UUIDReal, generado por el PAC de pruebasReal, con valor fiscal
Valor fiscal ante el SATNoSí
Consume timbres de tu saldoNo, nuncaSí, 1 por timbrado exitoso
Requiere certificación previaNoSí: contacta a soporte
Cómo se obtiene la keySe genera libre desde el portalSolo se genera si la cuenta está certificada
Vigencia de la key90 días de inactividad; se renueva al regenerarlaNo 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

  1. Integra y prueba con tu key de sandbox.
  2. Cuando funcione bien, contacta a soporte para certificar tu cuenta.
  3. Genera tu API key de producción desde el portal y cámbiala en tu integración. La URL no cambia.

Límites

Cómo cuidar tu API key

Tu API key es literalmente la contraseña de tu cuenta: quien la tenga puede timbrar, cancelar y consultar todo lo que tú puedes.

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 API

Documentació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.