API v1 · CFDI 4.0 · REST + JSON

Timbra CFDI 4.0 desde tu sistema con una sola llamada

Tú mandas el pedido; la API calcula los impuestos con el Anexo 20, valida las reglas del SAT, timbra y te regresa el UUID, el XML y el PDF. En pruebas desde el primer día, sin gastar timbres.

Petición
curl -X POST https://facturacion.cfdifacil.mx/api/v1/facturas \
  -H "Authorization: Bearer cfk_test_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "referencia": "PEDIDO-10025",
    "formaPago": "03",
    "receptor": { "rfc": "XAXX010101000", "nombre": "PUBLICO EN GENERAL",
                  "regimenFiscal": "616", "codigoPostal": "63000", "usoCfdi": "S01" },
    "global": { "periodicidad": "04", "meses": "11", "anio": "2026" },
    "conceptos": [{ "claveProdServ": "81111500", "claveUnidad": "E48",
                    "descripcion": "Soporte mensual", "cantidad": 1, "valorUnitario": 1000,
                    "impuestos": { "traslados": [{ "impuesto": "002", "tipoFactor": "Tasa", "tasaOCuota": 0.16 }] } }]
  }'
201 Created
{
  "success": true,
  "message": "Factura timbrada",
  "ambiente": "pruebas",
  "data": {
    "uuid": "6F1C2A9E-…",
    "serie": "A", "folio": "125",
    "subtotal": 1000, "total": 1160,
    "estado": "vigente",
    "repetida": false,
    "xml_url": "/api/v1/facturas/6F1C2A9E-…/xml",
    "pdf_url": "/api/v1/facturas/6F1C2A9E-…/pdf"
  }
}
CFDI 4.0Anexo 20 vigente
REST / JSONcualquier lenguaje
OpenAPI 3.0cliente autogenerado
2 ambientespruebas y producción
120 / minpeticiones por llave

Hecha para que tu integración no se rompa

Lo que más cuesta al facturar desde otro sistema son los duplicados, los rechazos del SAT y los errores que nadie entiende. La API resuelve los tres.

Nunca timbra dos veces

Mandas tu referencia (id del pedido). Si se corta la red y reintentas, la API regresa la misma factura con "repetida": true: sin duplicados ni timbres perdidos.

Tú mandas precios; nosotros el Anexo 20

Mandas cantidad, precio y tasa. El servidor calcula bases, importes, redondeos y totales con las reglas del Anexo 20 (incluido IVA sobre IEPS). Tu sistema no tiene que darle mantenimiento a las reglas del SAT.

Errores que dicen qué corregir

Cada error trae campo (ej. receptor.codigoPostal), error_code y un mensaje en español listo para mostrar a tu usuario. Si el error es de datos, no se gasta timbre.

Reglas del SAT antes de timbrar

Se validan antes de llegar al PAC: público en general con el C.P. del lugar de expedición, PPD con forma de pago 99, fecha de 72 h como máximo, factura global, extranjero con residencia fiscal… Menos rechazos y menos soporte.

Ambiente de pruebas idéntico

Misma URL y mismo código. Con cfk_test_… se timbra con el RFC y el PAC de pruebas del SAT, sin gastar timbres. Para salir a producción sólo cambias la llave.

OpenAPI 3.0: el cliente se genera solo

Con openapi.json generas el cliente tipado en .NET (NSwag o Visual Studio), Java, TypeScript, Go o Python con openapi-generator, sin escribir los modelos a mano.

Folios sin brincos

Si no mandas folio, el sistema asigna el siguiente de la serie, sin huecos ni repetidos aunque lleguen peticiones al mismo tiempo.

Estado real de la cancelación

Cancelación con los 4 motivos del SAT y sustitución. Consulta en todo momento si está vigente, cancelacion_en_proceso o cancelada.

El ciclo completo de la factura

Con el UUID que te regresa la API haces todo lo demás.

EmitirPOST /facturas
ConsultarGET /facturas/{uuid}
XML y PDFGET …/xml · …/pdf
Enviar por correoPOST …/enviar
CancelarPOST …/cancelar
MétodoRutaQué hace
GET/cuentaProbar la llave: ambiente, RFC emisor, regímenes y timbres disponibles.
POST/facturasEmitir (timbrar). 201 con UUID, folio y XML.
GET/facturasListar con filtros: fechas, RFC, estado, paginado (máx. 100).
GET/facturas/{uuid}Estado y totales.
GET/facturas/{uuid}/xml · /pdfDescargar el XML timbrado o el PDF.
POST/facturas/{uuid}/enviarEnviar XML y PDF a 1–5 correos.
POST/facturas/{uuid}/cancelarCancelar con motivo 01–04 (con sustitución).
POST/pagosComplemento de pago de tus facturas PPD. También consultar, XML, PDF, cancelar y enviar.
POST/timbrarTimbrar tu propio XML CFDI 4.0 (lo sellamos con tu certificado).
POST/ticketsAutofactura: registras la venta, imprimes el QR y tu cliente se factura solo.
POST/tickets/globalFactura global con los tickets que nadie facturó.

Elige cómo integrarte

Usa la que le quede a tu sistema. Todas timbran con el mismo PAC y quedan en la misma cuenta.

Mandas datos, armamos el XML

POST /facturas con un JSON sencillo. Nosotros calculamos impuestos y totales, armamos el CFDI, lo sellamos y lo timbramos.

Ya tienes tu XML

POST /timbrar con tu CFDI 4.0 sin sellar. Lo sellamos con el certificado de tu cuenta y lo timbramos.

Te pagaron una factura PPD

POST /pagos con la factura y el importe. Saldos, parcialidad e impuestos del complemento los pone el servidor.

Tu cliente se factura solo

POST /tickets al cobrar: imprimes el QR en el ticket, tu cliente pone su RFC y la factura se timbra y le llega por correo. Lo que nadie facture va a tu factura global.

Integra en tu lenguaje

Un encabezado y un JSON. Sin SDK obligatorio, sin SOAP, sin certificados en tu sistema.

Emitir factura
using System.Net.Http.Headers;
using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("https://facturacion.cfdifacil.mx/api/v1/") };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("CFDI_LLAVE"));

var resp = await http.PostAsJsonAsync("facturas", new {
    referencia = pedido.Id,                       // reintentos seguros
    formaPago  = "03",
    receptor   = new { rfc = c.Rfc, nombre = c.Nombre, regimenFiscal = c.Regimen,
                       codigoPostal = c.CP, usoCfdi = "G03" },
    conceptos  = pedido.Partidas.Select(p => new {
        claveProdServ = p.ClaveSat, claveUnidad = p.Unidad, descripcion = p.Nombre,
        cantidad = p.Cantidad, valorUnitario = p.Precio,
        impuestos = new { traslados = new[] { new { impuesto = "002", tipoFactor = "Tasa", tasaOCuota = 0.16m } } }
    })
});
var r = await resp.Content.ReadFromJsonAsync<JsonElement>();
if (!resp.IsSuccessStatusCode)                    // campo exacto + mensaje claro
    Mostrar(r.GetProperty("campo").GetString(), r.GetProperty("error").GetString());
const r = await fetch("https://facturacion.cfdifacil.mx/api/v1/facturas", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CFDI_LLAVE}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    referencia: pedido.id,
    formaPago: "03",
    receptor: { rfc, nombre, regimenFiscal: "601", codigoPostal: "06600", usoCfdi: "G03" },
    conceptos: pedido.partidas.map(p => ({
      claveProdServ: p.claveSat, claveUnidad: p.unidad, descripcion: p.nombre,
      cantidad: p.cantidad, valorUnitario: p.precio,
      impuestos: { traslados: [{ impuesto: "002", tipoFactor: "Tasa", tasaOCuota: 0.16 }] }
    }))
  })
});
const j = await r.json();
if (!r.ok) throw new Error(`${j.campo}: ${j.error}`);
console.log(j.data.uuid, j.data.total);
import os, requests

API = "https://facturacion.cfdifacil.mx/api/v1"
H = {"Authorization": f"Bearer {os.environ['CFDI_LLAVE']}"}

r = requests.post(f"{API}/facturas", headers=H, timeout=60, json={
    "referencia": pedido.id,
    "formaPago": "03",
    "receptor": {"rfc": rfc, "nombre": nombre, "regimenFiscal": "601",
                 "codigoPostal": "06600", "usoCfdi": "G03"},
    "conceptos": [{"claveProdServ": p.clave_sat, "claveUnidad": p.unidad,
                   "descripcion": p.nombre, "cantidad": p.cantidad, "valorUnitario": p.precio,
                   "impuestos": {"traslados": [{"impuesto": "002", "tipoFactor": "Tasa", "tasaOCuota": 0.16}]}}
                  for p in pedido.partidas],
})
j = r.json()
if not r.ok:
    raise ValueError(f"{j['campo']}: {j['error']}")
uuid = j["data"]["uuid"]
open(f"{uuid}.pdf", "wb").write(requests.get(f"{API}/facturas/{uuid}/pdf", headers=H).content)
$ch = curl_init("https://facturacion.cfdifacil.mx/api/v1/facturas");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("CFDI_LLAVE"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "referencia" => $pedido["id"],
        "formaPago"  => "03",
        "receptor"   => ["rfc" => $rfc, "nombre" => $nombre, "regimenFiscal" => "601",
                         "codigoPostal" => "06600", "usoCfdi" => "G03"],
        "conceptos"  => $conceptos,   // claveProdServ, claveUnidad, descripcion, cantidad, valorUnitario, impuestos
    ]),
]);
$j = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) throw new Exception($j["campo"] . ": " . $j["error"]);
echo $j["data"]["uuid"];

Qué facturas cubre

CFDI 4.0 de ingreso y egreso con todos los casos que vienen de un punto de venta, un ERP o una tienda en línea.

✓Factura de ingreso (I)PUE y PPD, cualquier forma de pago del catálogo c_FormaPago.
✓Nota de crédito / egreso (E)Con CFDI relacionados (01 nota de crédito, 03 devolución, 07 anticipo).
✓Factura globalPúblico en general con periodicidad, meses y año.
✓Cliente extranjeroXEXX010101000 con residencia fiscal y número de registro tributario.
✓SustituciónRelación 04 y cancelación con motivo 01 ligada al UUID nuevo.
✓ImpuestosIVA, IEPS e ISR; trasladados y retenidos; tasa, cuota o exento; objeto de impuesto automático.
✓Moneda extranjeraUSD, EUR, etc. con tipo de cambio.
✓DescuentosPor concepto, en pesos.
✓Complemento de pago (Pagos 2.0)Para tus facturas PPD: dices cuánto te pagaron de cada una; el servidor pone saldo anterior, parcialidad e impuestos proporcionales.
✓Tu propio XML¿Tu sistema ya genera el CFDI? Mándalo sin sellar: lo sellamos con el certificado de tu cuenta y lo timbramos.
✓Autofactura con ticketPara puntos de venta: registras la venta, imprimes el QR y tu cliente se factura solo; le llega por correo. Lo que nadie facture, en tu factura global con una llamada.

Complementos

Pagos, Impuestos Locales y Carta Porte los armamos nosotros desde un JSON. Los demás van dentro de tu XML: tu sistema arma el complemento y nosotros lo sellamos y lo timbramos.

ComplementoCómoRuta
✓Recepción de pagos (Pagos 2.0)Lo armamos nosotrosPOST /pagos: mandas qué facturas te pagaron y cuánto.
✓Impuestos LocalesLo armamos nosotrosPOST /facturas con «impuestosLocales»: mandas el impuesto y la tasa (ISH 3 %); importe y totales los calcula el servidor.
✓Carta Porte 3.1Lo armamos nosotrosPOST /facturas con «cartaPorte» (flete o traslado): ubicaciones, mercancías, vehículo y operador; IdCCP, kilómetros y pesos los pone el servidor.
✓Comercio ExteriorEn tu XMLPOST /timbrar con el complemento armado por tu sistema.
✓INE, Notarios Públicos, Donatarias, Divisas, Leyendas FiscalesEn tu XMLPOST /timbrar con el complemento armado por tu sistema.
✓Integrante Coordinado, Turista Pasajero Extranjero, Vehículos Usados, Servicio Parcial de ConstrucciónEn tu XMLPOST /timbrar con el complemento armado por tu sistema.

Seguridad

Vas a facturar a nombre de empresas reales. Así protegemos sus llaves y sus datos.

Llaves de 192 bits

Cada llave se ve una sola vez al crearla. En el servidor sólo se guarda su huella cifrada: aunque alguien la viera, no podría usarla.

HTTPS obligatorio

TLS con HSTS. La llave viaja en el encabezado Authorization: Bearer, nunca en la URL.

Firewall de aplicación

Todas las peticiones pasan por un firewall de aplicación web que filtra ataques conocidos antes de llegar a la API.

Límites contra abuso

Máximo 120 peticiones por minuto por llave (responde 429) y bloqueo automático de quien prueba llaves falsas. Las llaves de pruebas: 30 por minuto y 300 operaciones al día.

Bitácora de cada petición

Cada llamada queda registrada, para darte soporte con datos y no con suposiciones.

Revocable al instante

Si una llave se filtra, se desactiva y se te entrega otra sin tocar la cuenta, la contraseña ni el certificado.

De cero a producción en 4 pasos

Y en ninguno tienes que hablar con el SAT ni con un PAC.

Pide tu llave de pruebas

Te creamos una cuenta de pruebas y una llave cfk_test_….

Prueba la conexión

GET /cuenta debe responder "ambiente": "pruebas".

Timbra sin miedo

Emite, descarga y cancela todas las veces que quieras. No gasta timbres.

Cambia la llave

Con cfk_live_… ya timbras real. La URL y el código son los mismos.

Preguntas frecuentes

Lo que suelen preguntar los equipos de sistemas antes de integrarse.

¿Necesito contratar un PAC?

No. El timbrado ya está incluido: cada factura de producción usa un timbre del saldo de la cuenta. En pruebas no se gastan timbres.

¿Y si mis clientes tienen varios RFC?

Cada RFC es una cuenta con su certificado y su llave. Tu sistema guarda la llave de cada empresa y la usa al facturar por ella.

¿Dónde queda el certificado (CSD)?

Se carga una sola vez en la cuenta y se queda en el servidor. No viaja en las peticiones ni lo tiene que guardar tu sistema.

¿Qué pasa si el SAT o el PAC rechazan la factura?

Recibes 422 NO_TIMBRADA con la explicación en palabras claras. No se gasta timbre y puedes reintentar con la misma referencia ya corregida.

¿Puedo bajar el XML y el PDF?

Sí: GET /facturas/{uuid}/xml y /pdf. También puedes enviarlos por correo a 1–5 destinatarios con POST /facturas/{uuid}/enviar.

¿Y los complementos de pago?

Sí: POST /pagos con las facturas PPD que te pagaron y cuánto. El servidor calcula saldo anterior, número de parcialidad e impuestos de cada factura (Pagos 2.0). Cancelarlo regresa el saldo a las facturas.

Mi sistema ya genera el XML, ¿puedo sólo timbrarlo?

Sí: POST /timbrar con tu CFDI 4.0 sin sellar. Lo sellamos con el certificado de tu cuenta (el que traiga el XML se reemplaza) y lo timbramos. Queda en tus facturas como cualquier otra.

¿Mis clientes del mostrador pueden facturarse solos?

Sí: POST /tickets al cobrar te regresa una liga; ponla en un QR en el ticket. Tu cliente entra, escribe su RFC y la factura se timbra y le llega por correo. Tú consultas el estado con GET /tickets/{codigo}. El portal ya revisa que su RFC, régimen y uso de CFDI cuadren antes de timbrar.

¿Qué complementos puedo usar?

Pagos 2.0 (POST /pagos), Impuestos Locales y Carta Porte 3.1 (impuestosLocales y cartaPorte en POST /facturas) los armamos nosotros. Los demás (Comercio Exterior, INE, Notarios, Donatarias…) van dentro de tu XML con POST /timbrar: tu sistema arma el complemento y nosotros lo sellamos y lo timbramos.

¿Y lo que nadie facturó?

POST /tickets/global al cierre del mes (o de la semana o quincena con periodicidad, desde y hasta) junta los tickets sin facturar en una factura global a PUBLICO EN GENERAL. Esos tickets ya no se pueden facturar aparte, así que nunca se factura dos veces la misma venta.

¿Y la nómina?

Hoy se emite desde el portal web con la misma cuenta.

Empieza a probar hoy

Escríbenos con el nombre de tu sistema y el lenguaje en que está hecho. Te mandamos tu llave de pruebas y la liga a la documentación.