Documentación de la API · v1

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 relayModo sellar
Quién arma el XMLTú: lo armas y lo firmas con tu propio CSDTimbraMX: tú mandas datos en JSON
Qué mandas{ "xml": "…base64…" }Receptor, serie, método de pago, moneda y conceptos
Necesitas subir tu CSD al portalNoSí
Complementos (Carta Porte, Comercio Exterior…)Sí, porque tú armas todo el XMLNo: 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

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