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.
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 }] } }]
}'{
"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"
}
}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.
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.
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.
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.
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.
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.
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.
Si no mandas folio, el sistema asigna el siguiente de la serie, sin huecos ni repetidos aunque lleguen peticiones al mismo tiempo.
Cancelación con los 4 motivos del SAT y sustitución. Consulta en todo momento si está vigente, cancelacion_en_proceso o cancelada.
Con el UUID que te regresa la API haces todo lo demás.
POST /facturasGET /facturas/{uuid}GET …/xml · …/pdfPOST …/enviarPOST …/cancelar| Método | Ruta | Qué hace |
|---|---|---|
| GET | /cuenta | Probar la llave: ambiente, RFC emisor, regímenes y timbres disponibles. |
| POST | /facturas | Emitir (timbrar). 201 con UUID, folio y XML. |
| GET | /facturas | Listar con filtros: fechas, RFC, estado, paginado (máx. 100). |
| GET | /facturas/{uuid} | Estado y totales. |
| GET | /facturas/{uuid}/xml · /pdf | Descargar el XML timbrado o el PDF. |
| POST | /facturas/{uuid}/enviar | Enviar XML y PDF a 1–5 correos. |
| POST | /facturas/{uuid}/cancelar | Cancelar con motivo 01–04 (con sustitución). |
| POST | /pagos | Complemento de pago de tus facturas PPD. También consultar, XML, PDF, cancelar y enviar. |
| POST | /timbrar | Timbrar tu propio XML CFDI 4.0 (lo sellamos con tu certificado). |
| POST | /tickets | Autofactura: registras la venta, imprimes el QR y tu cliente se factura solo. |
| POST | /tickets/global | Factura global con los tickets que nadie facturó. |
Usa la que le quede a tu sistema. Todas timbran con el mismo PAC y quedan en la misma cuenta.
POST /facturas con un JSON sencillo. Nosotros calculamos impuestos y totales, armamos el CFDI, lo sellamos y lo timbramos.
POST /timbrar con tu CFDI 4.0 sin sellar. Lo sellamos con el certificado de tu cuenta y lo timbramos.
POST /pagos con la factura y el importe. Saldos, parcialidad e impuestos del complemento los pone el servidor.
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.
Un encabezado y un JSON. Sin SDK obligatorio, sin SOAP, sin certificados en tu sistema.
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"]; 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 global | Público en general con periodicidad, meses y año. |
| ✓Cliente extranjero | XEXX010101000 con residencia fiscal y número de registro tributario. |
| ✓Sustitución | Relación 04 y cancelación con motivo 01 ligada al UUID nuevo. |
| ✓Impuestos | IVA, IEPS e ISR; trasladados y retenidos; tasa, cuota o exento; objeto de impuesto automático. |
| ✓Moneda extranjera | USD, EUR, etc. con tipo de cambio. |
| ✓Descuentos | Por 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 ticket | Para 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. |
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.
| Complemento | Cómo | Ruta |
|---|---|---|
| ✓Recepción de pagos (Pagos 2.0) | Lo armamos nosotros | POST /pagos: mandas qué facturas te pagaron y cuánto. |
| ✓Impuestos Locales | Lo armamos nosotros | POST /facturas con «impuestosLocales»: mandas el impuesto y la tasa (ISH 3 %); importe y totales los calcula el servidor. |
| ✓Carta Porte 3.1 | Lo armamos nosotros | POST /facturas con «cartaPorte» (flete o traslado): ubicaciones, mercancías, vehículo y operador; IdCCP, kilómetros y pesos los pone el servidor. |
| ✓Comercio Exterior | En tu XML | POST /timbrar con el complemento armado por tu sistema. |
| ✓INE, Notarios Públicos, Donatarias, Divisas, Leyendas Fiscales | En tu XML | POST /timbrar con el complemento armado por tu sistema. |
| ✓Integrante Coordinado, Turista Pasajero Extranjero, Vehículos Usados, Servicio Parcial de Construcción | En tu XML | POST /timbrar con el complemento armado por tu sistema. |
Vas a facturar a nombre de empresas reales. Así protegemos sus llaves y sus datos.
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.
TLS con HSTS. La llave viaja en el encabezado Authorization: Bearer, nunca en la URL.
Todas las peticiones pasan por un firewall de aplicación web que filtra ataques conocidos antes de llegar a la API.
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.
Cada llamada queda registrada, para darte soporte con datos y no con suposiciones.
Si una llave se filtra, se desactiva y se te entrega otra sin tocar la cuenta, la contraseña ni el certificado.
Y en ninguno tienes que hablar con el SAT ni con un PAC.
Te creamos una cuenta de pruebas y una llave cfk_test_….
GET /cuenta debe responder "ambiente": "pruebas".
Emite, descarga y cancela todas las veces que quieras. No gasta timbres.
Con cfk_live_… ya timbras real. La URL y el código son los mismos.
Lo que suelen preguntar los equipos de sistemas antes de integrarse.
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.
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.
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.
Recibes 422 NO_TIMBRADA con la explicación en palabras claras. No se gasta timbre y puedes reintentar con la misma referencia ya corregida.
Sí: GET /facturas/{uuid}/xml y /pdf. También puedes enviarlos por correo a 1–5 destinatarios con POST /facturas/{uuid}/enviar.
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.
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.
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.
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.
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.
Hoy se emite desde el portal web con la misma cuenta.
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.
Rutas, campos, respuestas, errores y un ejemplo completo. Con el archivo OpenAPI generas el cliente en tu lenguaje sin escribir los modelos a mano.
https://facturacion.cfdifacil.mx/api/v1Cuatro pasos para timbrar tu primera factura de pruebas.
Escribe a soporte@cfdifacil.com.mx y recibes tu llave cfk_test_….
GET /cuenta con Authorization: Bearer cfk_test_… debe responder "ambiente": "pruebas".
POST /facturas con cantidades, precios y tasas. El servidor calcula importes, impuestos y totales.
Pide tu llave cfk_live_…. La URL y el código son los mismos.
Pega tu llave de pruebas, escoge la ruta y da «Enviar»: es la respuesta real del servidor. Las facturas de pruebas no tienen validez fiscal.
Sólo llaves cfk_test_. Nunca pegues tu llave de producción en un navegador.
// La respuesta aparece aquí
La llave decide el ambiente. Todas las respuestas traen "ambiente" para que nunca los confundas.
Timbra con el RFC y el PAC de pruebas del SAT. Las facturas no tienen validez fiscal y no gastan timbres. La cancelación no va al SAT.
Cada factura es real ante el SAT y gasta un timbre de la cuenta. Mismo código, misma URL.
En cada petición: Authorization: Bearer <llave>. Sin usuario ni contraseña de la cuenta.
Todas las rutas parten de la URL base y responden JSON (salvo XML y PDF).
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /cuenta | Probar la llave: ambiente, RFC con el que timbras, regímenes y timbres disponibles. |
| POST | /facturas | Emitir (timbrar). Responde 201 con UUID, folio y XML. |
| GET | /facturas | Listar. Filtros: desde, hasta (AAAA-MM-DD), rfc, estado, pagina, por_pagina (máx. 100). |
| GET | /facturas/{uuid} | Consultar estado y totales. |
| GET | /facturas/{uuid}/xml | Descargar el XML timbrado. |
| GET | /facturas/{uuid}/pdf | Descargar el PDF. |
| POST | /facturas/{uuid}/cancelar | {"motivo":"02"} · con motivo 01 agrega "uuidSustitucion". |
| POST | /facturas/{uuid}/enviar | {"correos":["cliente@dominio.com"]} (1 a 5). |
| POST | /pagos | Complemento de pago (Pagos 2.0): dices qué facturas PPD te pagaron y cuánto; el servidor arma saldos, parcialidad e impuestos. |
| GET | /pagos | Listar complementos. Mismos filtros que facturas. |
| GET | /pagos/{uuid} | Consultar: estado, monto y saldo de cada factura pagada. |
| GET | /pagos/{uuid}/xml | XML del complemento (también /pdf). |
| POST | /pagos/{uuid}/cancelar | {"motivo":"02"}. El saldo regresa a las facturas. |
| POST | /pagos/{uuid}/enviar | {"correos":["cliente@dominio.com"]} |
| POST | /timbrar | Timbrar TU propio XML CFDI 4.0 (I o E, sin sellar): lo sellamos con el certificado de tu cuenta y lo timbramos. |
| POST | /tickets | Autofactura: registra una venta y recibe la liga (para el QR del ticket). Tu cliente se factura solo. |
| GET | /tickets/{codigo} | Estado del ticket (esperando, facturado, vencido, cancelado) y UUID de la factura. |
| GET | /tickets | Listar tickets (estado, desde, hasta). |
| POST | /tickets/{codigo}/cancelar | Ya no se puede facturar (devolución). |
| POST | /tickets/global | Factura global con los tickets del periodo que nadie facturó: {"mes": 11, "anio": 2026}. Esos tickets ya no se pueden facturar aparte. |
Ejemplo de factura global a público en general. Tú mandas lo mínimo; lo demás lo calcula el servidor.
{
"referencia": "PEDIDO-10025",
"serie": "A",
"formaPago": "03",
"metodoPago": "PUE",
"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",
"unidad": "Servicio",
"descripcion": "Servicio de soporte mensual",
"cantidad": 1,
"valorUnitario": 1000.00,
"impuestos": {
"traslados": [ { "impuesto": "002", "tipoFactor": "Tasa", "tasaOCuota": 0.16 } ]
}
}
]
}| Campo | ¿Obligatorio? | Notas |
|---|---|---|
referencia | Recomendado | Id de la factura en TU sistema. Si mandas la misma dos veces (reintento por corte de red) se regresa la misma factura y no se gasta otro timbre. |
tipo | No | I ingreso (default) · E egreso / nota de crédito (requiere relacionados 01, 03 o 07) · T traslado (sólo con cartaPorte; el receptor lo pone el servidor). |
serie / folio | No | Si no mandas folio, el sistema pone el siguiente de la serie, sin brincos ni repetidos. |
fecha | No | AAAA-MM-DDTHH:MM:SS en hora del lugar de expedición. Default: ahora. Máximo 72 h atrás (regla del SAT). |
formaPago | Sí con PUE | c_FormaPago: 01 efectivo, 03 transferencia, 04 crédito, 28 débito… Con PPD se pone 99 sola (regla del SAT). |
metodoPago | No | PUE (default) o PPD. |
moneda / tipoCambio | No | MXN default. Otra moneda pide tipoCambio. |
lugarExpedicion / regimenEmisor | No | Por default los de tu cuenta. regimenEmisor es obligatorio sólo si tu cuenta tiene varios. |
receptor | Sí | rfc, nombre (como en su constancia), regimenFiscal, codigoPostal, usoCfdi. Para extranjero XEXX010101000 agrega residenciaFiscal y numRegIdTrib. |
conceptos[] | Sí | descripcion, cantidad, valorUnitario (SIN impuestos), descuento (pesos). Producto: claveProdServ + claveUnidad (se da de alta solo en tu catálogo) o noIdentificacion de uno ya dado de alta. |
conceptos[].impuestos | Sí con objetoImp 02 | traslados / retenciones: impuesto (002 IVA, 003 IEPS, 001 ISR), tipoFactor (Tasa, Cuota, Exento), tasaOCuota en decimal (0.16). Base e importe los calcula el servidor. Sin impuestos ⇒ objetoImp 01 (se pone solo). |
global | Sí con PUBLICO EN GENERAL | periodicidad (01 diaria, 02 semanal, 03 quincenal, 04 mensual), meses (01-12), anio. |
relacionados[] | No | tipoRelacion (01 nota de crédito, 04 sustitución, 07 anticipo…) y uuids. |
comentarios | No | Texto que sale en el PDF. |
impuestosLocales | No | Complemento Impuestos Locales: {"traslados": [{"impuesto": "ISH", "tasa": 3}], "retenciones": [...]}. Tasa en %; el importe (subtotal × tasa) y los totales los calcula el servidor. |
cartaPorte | No | Complemento Carta Porte 3.1 con los nombres de la guía del SAT: Ubicaciones (Origen/Destino), Mercancias (Mercancia, Autotransporte) y FiguraTransporte. IdCCP, TotalDistRec, PesoBrutoTotal y NumTotalMercancias los pone el servidor. Con tipo I el concepto es el flete (clave 78…). |
{
"success": true,
"message": "Factura timbrada",
"data": {
"uuid": "6F1C2A9E-…",
"serie": "A", "folio": "125",
"fecha": "2026-11-17T10:32:05",
"estado": "vigente",
"subtotal": 1000, "total": 1160,
"repetida": false,
"xml_base64": "PD94bWwg…",
"xml_url": "/api/v1/facturas/6F1C2A9E-…/xml",
"pdf_url": "/api/v1/facturas/6F1C2A9E-…/pdf"
},
"ambiente": "pruebas"
}{
"success": false,
"error": "Código postal de 5 dígitos del domicilio fiscal del cliente (el de su constancia).",
"error_code": "DATO_INVALIDO",
"campo": "receptor.codigoPostal",
"http_status": 400,
"ambiente": "pruebas"
}Cuando te pagan una factura PPD (completa o en parcialidades). Tú dices cuál y cuánto; el servidor calcula el resto con las reglas de Pagos 2.0.
{
"referencia": "COBRO-8841",
"formaPago": "03",
"fechaPago": "2026-11-18T10:30:00",
"numOperacion": "SPEI 0123456",
"documentos": [
{ "uuid": "91F5B976-4238-4FE4-A559-F47713D609A2", "importe": 500.00 }
]
}| Campo | ¿Obligatorio? | Notas |
|---|---|---|
documentos[] | Sí | Cada factura pagada: uuid (de una factura PPD vigente de tu cuenta) e importe (lo que te pagaron de ella). Todas del mismo cliente. Máximo 50. |
formaPago | Sí | Cómo te pagaron (c_FormaPago): 01 efectivo, 02 cheque, 03 transferencia, 04 crédito, 28 débito… No se permite 99. |
fechaPago | No | Día en que te pagaron (AAAA-MM-DD o con hora). Default: ahora. |
referencia | Recomendado | Id del cobro en tu sistema: si se repite, regresa el mismo complemento. |
moneda / tipoCambio | No | MXN default. Por API el pago va en la misma moneda que las facturas. |
numOperacion | No | Número de operación o referencia bancaria. |
serie / folio | No | Sin folio, el sistema pone el siguiente de la serie. |
sustituye | No | UUID del complemento que éste sustituye (relación 04). Después cancela el viejo con motivo 01. |
documentos[].numParcialidad | No | El sistema pone la que sigue. Mándala sólo si la llevas en tu sistema. |
{
"success": true,
"message": "Complemento de pago timbrado",
"data": {
"uuid": "0AD68245-…", "serie": "P", "folio": "57",
"fechaPago": "2026-11-18T10:30:00", "monto": 500,
"estado": "vigente",
"documentos": [ { "uuid": "91F5B976-…", "numParcialidad": 1,
"saldoAnterior": 1160, "importePagado": 500, "saldoInsoluto": 660 } ],
"xml_url": "/api/v1/pagos/0AD68245-…/xml",
"pdf_url": "/api/v1/pagos/0AD68245-…/pdf"
},
"ambiente": "pruebas"
}Si tu sistema ya genera el CFDI 4.0 (ingreso o egreso), mándalo sin sellar: lo sellamos con el certificado de tu cuenta y lo timbramos.
curl -X POST https://facturacion.cfdifacil.mx/api/v1/timbrar \
-H "Authorization: Bearer cfk_test_TU_LLAVE" \
-H "Content-Type: application/json" \
-d '{ "referencia": "FAC-A-1025", "xmlBase64": "PD94bWwgdmVyc2lvbj0iMS4wIi…" }'
# o el XML tal cual:
curl -X POST https://facturacion.cfdifacil.mx/api/v1/timbrar \
-H "Authorization: Bearer cfk_test_TU_LLAVE" \
-H "Content-Type: application/xml" \
--data-binary @factura.xmlEl NoCertificado, Certificado y Sello los pone el servidor con el certificado de la cuenta de la llave. El Rfc del emisor debe ser el de tu cuenta.
Mismo XML o misma referencia ⇒ la misma factura. Si la serie y folio ya existen, responde 409.
Manda el XML dentro de JSON (xml o xmlBase64): así un XML mal formado regresa un error con la línea exacta.
GET /facturas/{uuid}, /xml, /pdf, /cancelar, /enviar. El XML puede traer complementos (Impuestos Locales, Carta Porte, Comercio Exterior…): se timbran tal cual. En pruebas el emisor se cambia solo al RFC de pruebas del SAT. Máximo 2 MB, sin DOCTYPE.Para puntos de venta, restaurantes y tiendas en línea: tu cliente se factura solo y tú no capturas nada.
{
"referencia": "TICKET-000418",
"formaPago": "01",
"conceptos": [
{ "claveProdServ": "90101501", "claveUnidad": "E48",
"descripcion": "Comida corrida", "cantidad": 2, "valorUnitario": 86.21,
"impuestos": { "traslados": [ { "impuesto": "002", "tipoFactor": "Tasa", "tasaOCuota": 0.16 } ] } }
]
}{
"success": true,
"message": "Ticket registrado",
"data": {
"codigo": "EZRKAJ3A",
"liga": "https://facturacion.cfdifacil.mx/autofactura/f/EZRKAJ3A",
"total": 200.01,
"vence": "2026-11-30",
"estado": "esperando",
"factura": null
}
}conceptos que en POST /facturas (precio sin impuestos + tasas). El servidor calcula el total exacto.liga como código QR en el ticket.GET /tickets/{codigo} ves el UUID.POST /tickets/global con {"mes": 11, "anio": 2026} timbra la factura global a PUBLICO EN GENERAL con todos los tickets que nadie facturó (conceptos reales, Información Global y la forma de pago del mayor importe). Esos tickets quedan «en_global» y su liga ya no deja facturar.Cada error trae error (qué pasó, en español), error_code y campo (dónde corregir).
| Código | Significado |
|---|---|
200 / 201 | Correcto (201 = factura nueva timbrada). |
400 DATO_INVALIDO | Un dato está mal. «campo» dice cuál (ej. conceptos[0].claveProdServ) y «error» cómo corregirlo. No se gastó timbre. |
401 | Falta la llave o no es válida. |
403 CUENTA_INCOMPLETA | La cuenta aún no puede facturar (falta certificado, régimen o formato). |
404 | No existe esa factura en tu cuenta. |
409 | Ya está cancelada. |
422 NO_TIMBRADA | El SAT o el PAC la rechazaron, o falló una regla del SAT. «error» explica en palabras claras. No se gastó timbre. |
429 | Más de 120 peticiones por minuto. Espera y reintenta. |
5xx | Falla temporal. Reintenta con la MISMA «referencia» para no duplicar. |
.NET 6 o más nuevo: probar la llave, emitir y descargar XML y PDF.
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
var http = new HttpClient { BaseAddress = new Uri("https://facturacion.cfdifacil.mx/api/v1/") };
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "cfk_test_TU_LLAVE"); // pruebas
// 1) Probar la llave
Console.WriteLine(await http.GetStringAsync("cuenta"));
// 2) Emitir
var factura = new {
referencia = "PEDIDO-10025", serie = "A", formaPago = "03", metodoPago = "PUE",
receptor = new { rfc = "XAXX010101000", nombre = "PUBLICO EN GENERAL",
regimenFiscal = "616", codigoPostal = "63000", usoCfdi = "S01" },
global = new { periodicidad = "04", meses = "11", anio = "2026" },
conceptos = new[] { new {
claveProdServ = "81111500", claveUnidad = "E48", unidad = "Servicio",
descripcion = "Servicio de soporte mensual", cantidad = 1m, valorUnitario = 1000m,
impuestos = new { traslados = new[] { new { impuesto = "002", tipoFactor = "Tasa", tasaOCuota = 0.16m } } }
} }
};
var cuerpo = new StringContent(JsonSerializer.Serialize(factura), Encoding.UTF8, "application/json");
var resp = await http.PostAsync("facturas", cuerpo);
var json = JsonDocument.Parse(await resp.Content.ReadAsStringAsync()).RootElement;
if (!resp.IsSuccessStatusCode)
throw new Exception($"{json.GetProperty("error")} (campo: {json.GetProperty("campo")})");
var uuid = json.GetProperty("data").GetProperty("uuid").GetString();
// 3) Descargar XML y PDF
File.WriteAllBytes($"{uuid}.xml", await http.GetByteArrayAsync($"facturas/{uuid}/xml"));
File.WriteAllBytes($"{uuid}.pdf", await http.GetByteArrayAsync($"facturas/{uuid}/pdf"));Lo que evita duplicados, rechazos y llaves filtradas.
Manda referencia y, si se corta la red, reintenta con la misma: nunca se timbra dos veces.
Con él consultas, descargas, envías y cancelas cada factura.
Nunca en una app de celular ni en JavaScript del navegador. Si se filtra, se desactiva y se te da otra.
Si recibes 429, espera unos segundos y reintenta.
Escríbenos con el nombre de tu sistema y el lenguaje en que está hecho y te mandamos tu llave de pruebas.