Cómo timbrar tu primera factura por API
Timbra un CFDI 4.0 con una sola petición HTTP: configuración, solicitud en curl, Node.js y Python, y cómo leer la respuesta. Prueba gratis en sandbox.
En este paso a paso timbras una factura de Ingreso con el modo sellar: tú mandas los datos del comprobante en JSON y TimbraMX arma el XML CFDI 4.0, lo sella con tu CSD y lo timbra. No necesitas construir ni firmar el XML tú mismo.
Antes de empezar: configuración en el portal
La API nunca crea clientes, series ni sube tu CSD. Eso se prepara una sola vez desde el portal web:
- Crea tu cuenta en app.timbra-mx.com, gratis y sin tarjeta.
- Sube tu CSD en Mi empresa → CSD. Es obligatorio para timbrar en modo sellar.
- Da de alta al menos un cliente en Mis clientes. La API rechaza con error 400 un
receptorRfcque no exista en tu catálogo. - Crea una serie activa para el tipo de documento que vas a timbrar. Sin una serie activa, la API rechaza con error 400.
- Activa el módulo de API. Sin él, toda llamada regresa 403.
- Genera tu API key de sandbox desde la vista “API” del portal. No requiere aprobación y está disponible al instante.
Paso 1: manda la solicitud de timbrado
Haz un POST a https://app.timbra-mx.com/api/v1/facturas con tu API key en el header X-Api-Key. Reemplaza TU_API_KEY por tu key de sandbox:
curl
curl -X POST https://app.timbra-mx.com/api/v1/facturas \
-H "X-Api-Key: TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"receptorRfc": "XAXX010101000",
"serie": "F",
"metodoPago": "PUE",
"moneda": "MXN",
"conceptos": [{
"claveProdServ": "81112101",
"claveUnidad": "E48",
"descripcion": "Servicio de consultoría",
"cantidad": 1,
"valorUnitario": 1000,
"impuestos": [{ "impuesto": "002", "categoria": "traslado", "tipoFactor": "Tasa", "tasaIva": 0.16 }]
}]
}'Node.js
const respuesta = await fetch("https://app.timbra-mx.com/api/v1/facturas", {
method: "POST",
headers: {
"X-Api-Key": process.env.TIMBRAMX_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
receptorRfc: "XAXX010101000",
serie: "F",
metodoPago: "PUE",
moneda: "MXN",
conceptos: [{
claveProdServ: "81112101",
claveUnidad: "E48",
descripcion: "Servicio de consultoría",
cantidad: 1,
valorUnitario: 1000,
impuestos: [{ impuesto: "002", categoria: "traslado", tipoFactor: "Tasa", tasaIva: 0.16 }],
}],
}),
});
const resultado = await respuesta.json();
if (!resultado.ok) throw new Error(resultado.error);
console.log("UUID fiscal:", resultado.data.uuidFiscal);Python
import os, requests
resp = requests.post(
"https://app.timbra-mx.com/api/v1/facturas",
headers={"X-Api-Key": os.environ["TIMBRAMX_API_KEY"], "Content-Type": "application/json"},
json={
"receptorRfc": "XAXX010101000",
"serie": "F",
"metodoPago": "PUE",
"moneda": "MXN",
"conceptos": [{
"claveProdServ": "81112101",
"claveUnidad": "E48",
"descripcion": "Servicio de consultoría",
"cantidad": 1,
"valorUnitario": 1000,
"impuestos": [{"impuesto": "002", "categoria": "traslado", "tipoFactor": "Tasa", "tasaIva": 0.16}],
}],
},
)
data = resp.json()
if not data["ok"]:
raise Exception(data["error"])
print("UUID fiscal:", data["data"]["uuidFiscal"])Paso 2: lee la respuesta
Si todo sale bien, regresa ok: true y el comprobante timbrado:
Respuesta
{
"ok": true,
"data": {
"id": "ID-INTERNO-DE-TIMBRAMX",
"estado": "timbrada",
"uuidFiscal": "A1B2C3D4-...",
"serie": "F",
"folio": "1",
"total": 1160,
"timbradaEn": "2026-10-27T12:00:00",
"xml": "PD94bWwgdmVyc2lvbj0iMS4wIi..."
}
}ides el identificador interno de TimbraMX. Úsalo para consultar, descargar o cancelar. No es el UUID fiscal.uuidFiscales el folio fiscal que asigna el SAT y es el que identifica tu CFDI ante el mundo fiscal.xmltrae el CFDI timbrado completo, en base64. Decodifícalo para obtener el XML.
Guarda el id y el uuidFiscal en tu propio sistema.
Paso 3: descarga el XML y el PDF
curl
curl https://app.timbra-mx.com/api/v1/facturas/ID-INTERNO-DE-TIMBRAMX/xml -H "X-Api-Key: TU_API_KEY" -o factura.xml
curl https://app.timbra-mx.com/api/v1/facturas/ID-INTERNO-DE-TIMBRAMX/pdf -H "X-Api-Key: TU_API_KEY" -o factura.pdfProbar en sandbox no gasta timbres
Con la key de sandbox el timbrado es real contra el ambiente de pruebas del proveedor de timbrado: mismas validaciones y reglas de negocio, con UUID real pero sin valor fiscal y sin consumir tu saldo de timbres. Cuando tu integración funcione, pide la certificación de tu cuenta para generar la key de producción. Más detalles en Autenticación y ambientes.
¿Algo salió mal?
Todo error regresa { "ok": false, "error": "..." }. Consulta Errores y reintentos para saber qué hacer con cada código, y la matriz de errores del CFDI para entender los rechazos del SAT.
Preguntas frecuentes
¿Necesito armar y firmar el XML yo mismo?
No, si usas el modo sellar: mandas los datos en JSON y TimbraMX arma, sella con tu CSD y timbra. Si prefieres armar tu propio XML, usa el modo relay.
¿Cuánto cuesta timbrar por API?
Cada timbrado exitoso en producción consume 1 timbre de tu saldo, igual que desde el portal. Usar la API no tiene costo adicional. El sandbox no consume timbres.
¿Puedo probar sin gastar timbres?
Sí. La API key de sandbox timbra contra el ambiente de pruebas, sin valor fiscal y sin consumir tu saldo.
¿Qué lenguajes puedo usar?
Cualquiera que haga peticiones HTTP con JSON: Node.js, Python, PHP, Java, .NET o curl. No hay un SDK propietario que instalar.
¿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.