Complemento de pago y notas de crédito por API
Cómo timbrar un complemento de pago (CFDI tipo P) y una nota de crédito por API: campos que mandas, lo que calcula TimbraMX, errores y ejemplos en curl, Node.js y Python.
Además de facturas de Ingreso, la API cubre dos documentos que se usan todos los días: el complemento de pago (CFDI tipo P) y la nota de crédito. La estructura oficial de cada nodo está definida en el Anexo 20 del SAT; esta guía solo explica cómo enviarlo por la API.
Complemento de pago (CFDI tipo P)
POST https://app.timbra-mx.com/api/v1/complementos-pago timbra un complemento de pago para una o varias facturas con método de pago PPD ya timbradas. Las facturas se identifican por su UUID fiscal (facturaUuid), no por el id interno, y deben estar timbradas y ser del mismo receptor. Un pago puede cubrir varios documentos, y el body puede traer varios pagos en un solo complemento. Soporta Idempotency-Key.
Lo que mandas: el RFC del receptor, la serie y, por cada pago, sus documentos cubiertos con el monto aplicado. Lo que calcula TimbraMX: el saldo insoluto y anterior de cada factura (los lee de la factura original), el total del complemento, el folio, el sello y el UUID fiscal.
Request
{
"receptorRfc": "COE850101AB1",
"serie": "PAGOS",
"pagos": [{
"fechaPago": "2026-09-15T12:00:00",
"formaPago": "03",
"moneda": "MXN",
"documentos": [{
"facturaUuid": "3F9A1C2E-...",
"impPagado": 12500.00
}]
}]
}Python
import os, requests
resp = requests.post(
"https://app.timbra-mx.com/api/v1/complementos-pago",
headers={
"X-Api-Key": os.environ["TIMBRAMX_API_KEY"],
"Content-Type": "application/json",
},
json={
"receptorRfc": "COE850101AB1",
"serie": "PAGOS",
"pagos": [{
"fechaPago": "2026-09-15T12:00:00",
"formaPago": "03",
"moneda": "MXN",
"documentos": [
{"facturaUuid": "3F9A1C2E-...", "impPagado": 12500.00}
],
}],
},
)
data = resp.json()
print("Complemento de pago:", data["data"]["id"])Errores propios del complemento de pago: PAG-001 monto pagado inválido, PAG-002 forma de pago inválida, PAG-004 pago sin documentos, PAG-005 falta tipo de cambio (moneda distinta de MXN), PAG-008 sin pagos, PAG-009 falta el UUID y PAG-010 falta el RFC del receptor.
Nota de crédito
POST https://app.timbra-mx.com/api/v1/facturas/:id/nota-credito acredita, total o parcialmente, una factura de Ingreso ya timbrada con la misma API key. El :id es el id interno que regresó el timbrado, no el UUID fiscal. La forma de pago se copia de la factura original, regla del Anexo 20, y el método de pago siempre es PUE.
curl
curl -X POST https://app.timbra-mx.com/api/v1/facturas/$FACTURA_ID/nota-credito \
-H "X-Api-Key: $TIMBRAMX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"importe":1160.00,"descripcion":"Devolución de mercancía","serie":"NC"}'Node.js
const res = await fetch(
`https://app.timbra-mx.com/api/v1/facturas/${facturaId}/nota-credito`,
{
method: "POST",
headers: {
"X-Api-Key": process.env.TIMBRAMX_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
importe: 1160.00,
descripcion: "Devolución de mercancía",
serie: "NC",
}),
}
);
const data = await res.json();
console.log("Nota de crédito:", data.data.uuidFiscal);Errores propios: NC-002 importe inválido (mayor al total de la factura original) y NC-003 falta la descripción.
Qué no cubre la API hoy
- El modo sellar solo arma CFDI de Ingreso simple, sin complementos.
- Retenciones: solo 3 de los 12 tipos del catálogo del SAT (dividendos, enajenación de acciones y pagos al extranjero) están disponibles por API.
- Addendas: se agregan a una factura ya timbrada solo desde el portal; todavía no hay endpoint de API.
- No hay webhooks: para saber si algo cambió, consulta con
GET /:id.
Preguntas frecuentes
¿Cuándo se necesita el complemento de pago?
Cuando facturaste con método de pago PPD (pago en parcialidades o diferido) y después recibes el pago: se emite un CFDI tipo P por cada pago recibido.
¿El complemento de pago consume un timbre?
Sí, como cualquier CFDI timbrado en producción. En sandbox no consume timbres.
¿Puedo cubrir varias facturas con un solo pago?
Sí. Un pago puede cubrir varios documentos y un complemento puede traer varios pagos.
¿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.