API Masivo de Timbra: timbrado CFDI 4.0 con sandbox y cancelación por UUID ​

by Manolo Garcia · 20 de octubre de 2026

Si hoy integras facturación en tu ERP, tu CRM o tus scripts de back office, esta actualización te ahorra trabajo y dinero. Actualizamos el API Masivo de Timbra con tres cosas que cambian la forma de integrar: un ambiente de pruebas que no cuesta ni un timbre, la cancelación por UUID para que no tengas que manejar certificados en cada llamada, y la posibilidad de operar con paquetes de timbrado prepagados aunque no tengas una suscripción mensual activa.

Además, la documentación completa ya está publicada y es 100% compatible con el estándar de SW Sapien, así que si vienes de ahí la migración es directa.

El API Masivo en una línea ​

Una API REST que recibe JSON o XML y devuelve el CFDI timbrado con su UUID. La URL base es siempre la misma:

https://dashboard.timbra.com.mx/api/masivo

Y la autenticación es un token Bearer que generas desde el panel, en la sección API Keys:

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

Ese header es lo único que cambia entre producción y pruebas. No hay URLs distintas, no hay parámetros extra: el ambiente lo define el tipo de llave que envías.

Dos ambientes desde la misma URL ​

Para las pruebas usamos los RFCs oficiales de prueba del SAT: EKU9003173C9 (persona moral), AAA010101AAA (persona física), URE180429TM6 y ESI920427880. Si el RFC del emisor no está en esa lista, la API responde con un 400 explicando que solo se admiten RFCs de prueba.

La consecuencia práctica: puedes correr tus pruebas completas, con el mismo código y los mismos payloads, sin consumir un solo timbre. Cuando la integración está lista, cambias la llave y sigues.

Timbrado desde JSON o desde XML ​

Si tu sistema ya tiene los datos de la factura estructurados, el camino más corto es el timbrado desde JSON: mandas emisor, receptor, conceptos e impuestos, y Timbra arma el XML, lo sella y lo timbre.

{
  "Version": "4.0",
  "TipoDeComprobante": "I",
  "Emisor": { "Rfc": "EKU9003173C9", "Nombre": "ESCUELA KEMPER URGATE", "RegimenFiscal": "601" },
  "Receptor": { "Rfc": "XAXX010101000", "Nombre": "PUBLICO EN GENERAL", "UsoCFDI": "S01" },
  "Conceptos": [{ "ClaveProdServ": "84111506", "Cantidad": "1", "Importe": "1000.00" }],
  "SubTotal": "1000.00",
  "Total": "1160.00",
  "Moneda": "MXN",
  "FormaPago": "01",
  "MetodoPago": "PUE",
  "LugarExpedicion": "64000"
}

Y si ya generas XML en tu ERP, lo mandas tal cual en el campo data. No necesitas sellarlo: Timbra genera el sello y el certificado antes de timbrar. Eso eliminó de la ecuación uno de los pasos que más errores causaba.

Cancelación por UUID ​

Hasta ahora, cancelar un comprobante por API exigía enviar el CSD del emisor en cada llamada. Ya no es así. La cancelación por UUID funciona en dos variantes:

# Con JSON en el cuerpo
curl -X POST "https://dashboard.timbra.com.mx/api/masivo/cfdi33/cancel/uuid" \
  -H "Authorization: Bearer tmb_live_tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "A1B2C3D4-5E6F-7890-ABCD-EF1234567890", "motivo": "02" }'

# Con los datos en la ruta
curl -X POST "https://dashboard.timbra.com.mx/api/masivo/cfdi33/cancel/EKU9003173C9/A1B2C3D4-5E6F-7890-ABCD-EF1234567890/02" \
  -H "Authorization: Bearer tmb_live_tu_api_key_aqui"

Timbra resuelve la firma con los certificados que ya tienes cargados en tu cuenta, así que tus integraciones no tienen que exponer ni rotar claves privadas. El motivo de cancelación sigue el catálogo del SAT (01 a 04) y la respuesta incluye el acuse en XML, que es el comprobante de que la operación se realizó.

Factura con paquetes prepagados, sin suscripción mensual ​

Antes, operar por API exigía una suscripción de SaaS activa. Ahora tu saldo de timbres es suficiente: si tienes timbres prepagados, puedes timbrar sin tener un plan mensual vigente.

En la práctica:

• Cada CFDI emitido en Live descuenta 1 timbre de tu saldo.
• La cancelación no consume timbres.
• En el ambiente de pruebas no se descuenta nada.
• Si el saldo no alcanza, la respuesta trae errorCode: TIMBRES_INSUFICIENTES y puedes actuar en tu código sin interpretar el mensaje en texto.

Esto habilita un modelo que antes no existía: un integrador o un reseller que compra un paquete de timbrado y revende timbres a sus clientes, sin contratar un plan completo.

Documentación completa y colección de Postman ​

Publicamos la referencia técnica de la API con el detalle de cada endpoint, los campos del cuerpo, las respuestas, los errores más comunes y ejemplos en cURL, JavaScript y Python:

• Documentación de la API Masivo
• Autenticación y API Keys
• Ambientes Live y Test
• Timbrado desde JSON y desde XML
• Cancelación por CSD y por UUID
• Errores y códigos de respuesta

Además publicamos una colección de Postman lista para importar, con los cinco requests (los dos timbrados y las tres cancelaciones) y un environment de sandbox para que puedas probarlos en minutos. La descargas están en timbra.com.mx/api/postman.

¿Listo para integrar? ​

• Prueba sin riesgo: crea una llave tmb_test_... en el panel y valida tu flujo completo sin gastar timbres.
• Sin CSD en el código: la cancelación por UUID resuelve la firma con los certificados de tu cuenta.
• Escala con tu volumen: pasa a una llave tmb_live_... cuando estés listo y consume de tu saldo prepagado.
• Documentación y soporte: si te atoras en un código de error, la guía de errores lista cada caso y nosotros te ayudamos.

Empieza con un plan gratuito de 30 días o, si ya tienes tu CSD listo, crea tu cuenta y genera tu API Key en API Keys.

¿Dudas sobre la integración? Contáctanos y un asesor te ayuda sin costo.