Timbrar CFDI con Python, Node.js y PHP
Ejemplos listos para copiar para timbrar facturas por API en Node.js, Python, PHP y C#, en modo relay (tu XML) o modo sellar (en JSON).
La API de TimbraMX es una API REST con JSON: no hay SDK propietario que instalar. Funciona igual desde Python, Node.js, PHP, Java, .NET o cualquier lenguaje que haga peticiones HTTP. Hay dos formas de timbrar, según quién arma el XML.
| Modo relay | Modo sellar | |
|---|---|---|
| Quién arma el XML | Tú: lo armas y lo firmas con tu propio CSD | TimbraMX: tú mandas datos en JSON |
| Qué mandas | { "xml": "…base64…" } | Receptor, serie, método de pago, moneda y conceptos |
| Necesitas subir tu CSD al portal | No | Sí |
| Complementos (Carta Porte, Comercio Exterior…) | Sí, porque tú armas todo el XML | No: solo CFDI de Ingreso simple |
Modo relay: ya tienes el XML sellado
Asumiendo que armaste y sellaste el XML de tu CFDI 4.0 con tu CSD, lo envías en base64:
Node.js
const xmlBase64 = Buffer.from(xmlSellado, "utf8").toString("base64");
const res = 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({ xml: xmlBase64 }),
});
const data = await res.json();
if (!data.ok) throw new Error(data.error);
console.log("UUID fiscal:", data.data.uuidFiscal);Python
import base64, os, requests
xml_base64 = base64.b64encode(xml_sellado.encode("utf-8")).decode()
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={"xml": xml_base64},
)
data = resp.json()
if not data["ok"]:
raise Exception(data["error"])
print("UUID fiscal:", data["data"]["uuidFiscal"])PHP
$xmlBase64 = base64_encode($xmlSellado);
$ch = curl_init("https://app.timbra-mx.com/api/v1/facturas");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-Api-Key: " . getenv("TIMBRAMX_API_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode(["xml" => $xmlBase64]),
]);
$data = json_decode(curl_exec($ch), true);
if (!$data["ok"]) {
throw new Exception($data["error"]);
}
echo "UUID fiscal: " . $data["data"]["uuidFiscal"];Si quieres comprobar el XML antes de gastar un intento, POST https://app.timbra-mx.com/api/v1/facturas/validar lo valida sin timbrarlo.
Modo sellar: nosotros armamos el XML
Subes tu CSD al portal una sola vez y mandas los datos del comprobante en JSON. Aquí van los ejemplos en Laravel (PHP) y C#; en la guía de tu primera factura están en curl, Node.js y Python.
PHP (Laravel)
$response = Http::withHeaders([
'X-Api-Key' => config('services.timbramx.api_key'),
'Content-Type' => 'application/json',
])->post('https://app.timbra-mx.com/api/v1/facturas', [
'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,
]],
]],
]);
$factura = $response->json('data');C# / .NET
var body = new {
receptorRfc = "XAXX010101000",
serie = "F",
metodoPago = "PUE",
moneda = "MXN",
conceptos = new[] {
new {
claveProdServ = "81112101",
claveUnidad = "E48",
descripcion = "Servicio de consultoría",
cantidad = 1,
valorUnitario = 1000,
impuestos = new[] { new { impuesto = "002", categoria = "traslado", tipoFactor = "Tasa", tasaIva = 0.16 } },
},
},
};
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", apiKey);
var response = await client.PostAsJsonAsync("https://app.timbra-mx.com/api/v1/facturas", body);
var resultado = await response.Content.ReadFromJsonAsync<JsonElement>();En cualquier lenguaje, usa tu API key de sandbox para probar y la de producción cuando tu cuenta esté certificada. La URL no cambia nunca.
Seguridad de tu API key
- Úsala solo desde tu servidor, nunca en un navegador, app móvil o código que el usuario pueda inspeccionar.
- No la subas a un repositorio: guárdala en variables de entorno o en tu manejador de secretos.
- Excluye el header
X-Api-Keyde tus logs. - La API solo acepta HTTPS.
Preguntas frecuentes
¿Cuál modo me conviene, relay o sellar?
Si ya tienes un sistema que arma y firma CFDI, usa relay. Si prefieres no manejar XML ni sellos, usa sellar. Si necesitas complementos como Carta Porte o Comercio Exterior, necesitas relay.
¿Hay una librería o SDK?
No hace falta. Son peticiones HTTP con JSON, así que funciona con la librería de HTTP de tu lenguaje.
¿Cuál es la URL base?
https://app.timbra-mx.com/api/v1, la misma para sandbox y producción. Lo que cambia es la API key.
¿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.