Timbra

Appearance

On this page

Saldo prepagado y timbres ​

La API Masivo consume timbres de tu cuenta cuando emite CFDI reales. Puedes tener saldo por un plan mensual o por un paquete de timbres prepagado.

Cómo se descuenta el saldo ​

  • Live: cada CFDI timbrado correctamente descuenta 1 timbre.
  • Test / Sandbox: no descuenta timbres, sin importar cuántas pruebas hagas.
  • Cancelación: no consume timbres.
  • Errores: si el timbrado falla, no se descuenta el timbre.

Paquetes prepagados sin suscripción mensual ​

Puedes timbrar con un paquete de timbres prepagado aunque no tengas una suscripción mensual activa. La API autoriza el timbrado cuando tu saldo de timbres es suficiente para la operación.

SituaciónResultado
Saldo de timbres mayor o igual a 1Timbra correctamente, con o sin suscripción mensual activa.
Saldo de timbres en 0 y sin suscripciónError TIMBRES_INSUFICIENTES.
Saldo en 0 y suscripción activa no ilimitadaError TIMBRES_INSUFICIENTES. Recarga tu saldo.
Plan ilimitadoTimbra y, si hace falta, se recarga automáticamente.

Esto significa que un paquete prepagado es suficiente para operar por API. No necesitas contratar un plan SaaS mensual solo para timbrar.

Consultar y recargar tu saldo ​

Puedes consultar tu saldo disponible en el panel de Timbra. Para recargar, elige un paquete de timbres:

Error por saldo insuficiente ​

Cuando no hay saldo suficiente, la API responde con HTTP 400:

json
{
  "status": "error",
  "message": "Timbres insuficientes. Disponibles: 0, Requeridos: 1",
  "errorCode": "TIMBRES_INSUFICIENTES"
}

El campo errorCode te permite identificar el caso sin depender del texto del mensaje.

Buenas prácticas ​

  • Monitorea tu saldo antes de procesos masivos. Un lote grande puede agotar el saldo a la mitad.
  • Distingue Live de Test. Una llave tmb_live_... consume saldo real; una tmb_test_... no.
  • No reintentes a ciegas un error de saldo: recarga primero. Reintentar sin saldo produce el mismo error.
  • Guarda el UUID y el XML de cada CFDI timbrado. La API los devuelve en la respuesta.
  • Usa el acuse de cancelación como comprobante de la operación.

Consulta Errores y códigos de respuesta para ver otros casos y cómo reaccionar a cada uno.