FISCALISTO / API / REFERENCIA
Timbrar un complemento de pago
El recibo de pago (CFDI tipo P, Pagos 2.0) de facturas PPD: parcialidad, saldo anterior e insoluto e impuestos de cada una los calcula Fiscalisto.
bearerAuthAutorizaciónBearer <llave>Su llave secreta: fk_test_… en pruebas, fk_live_… en producción. Desarrolladores › Llaves.
Idempotency-Key*stringUno nuevo por comprobante (8 a 255 caracteres; su id de pedido sirve). Si la respuesta se pierde, repita la solicitud con el mismo valor: contesta lo mismo y nunca se timbra dos veces.
8 <= length <= 255application/json- body
issuer?stringEmisor (iss_…). Si la llave tiene un solo emisor o la cuenta tiene uno solo, puede omitirse.
date?stringFecha en que le pagaron (FechaPago), AAAA-MM-DD. Por omisión hoy.
^\d{4}-\d{2}-\d{2}$payment_form*stringForma de pago (FormaPago), clave de c_FormaPago: 01 efectivo, 03 transferencia, 04 tarjeta de crédito, 28 débito, 99 por definir… Obligatoria con PUE; con PPD es 99.
^\d{2}$operation_number?|Número de operación del pago (NumOperacion), como el rastreo SPEI.
currency?stringMoneda, clave ISO 4217 de c_Moneda (MXN, USD, EUR…). Por omisión MXN.
3 <= length <= 3exchange_rate?|Tipo de cambio a pesos (TipoCambio). Obligatorio si la moneda no es MXN; use el del DOF del día anterior.
series?stringSerie (Serie), hasta 25 caracteres. Cada serie lleva sus propios folios.
length <= 25documents*array<>Las facturas que paga (DoctoRelacionado).
1 <= items <= 100send_email?booleantrue para mandar el PDF y el XML por correo al timbrar, con el diseño de Fiscalisto. Por omisión no se envía.
email?stringCorreo a donde se envía (varios separados por comas). Solo se usa si se pide enviarlo.
^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$emailemail_cc?|Correos con copia, separados por comas.
metadata?Sus propios datos: hasta 50 llaves de 40 caracteres con valores de texto de hasta 500. No van al CFDI; vuelven en el objeto y en los webhooks.
bank_transaction?stringEl depósito (btx_…) con que le pagaron: queda conciliado con este complemento, y date es su día si no manda otra.
Correcto. Repetir la solicitud con la misma Idempotency-Key contesta lo mismo, con el mismo status y el encabezado idempotent-replayed: true.
application/json- response
Un CFDI 4.0 emitido: factura de ingreso o global, traslado, nota de crédito (E), complemento de pago (P) o recibo de nómina (N).
id*stringIdentificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_).
livemode*booleantrue en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT.
object*stringQué tipo de objeto es («invoice», «customer»…).
issuer*stringEl emisor (iss_…).
branch*|La sucursal (brn_…) desde donde se timbró, o null (el domicilio fiscal del emisor). Sus pagos y notas de crédito la siguen.
type*stringTipo de comprobante (TipoDeComprobante): I ingreso, E egreso, P pago, T traslado, N nómina.
"I""E""P""T""N"status*stringprocessing: el PAC no ha contestado (se resuelve sola; escuche invoice.stamped). valid: timbrada. pending: timbrada con una cancelación en espera del cliente. rejected: el SAT o el PAC no la aceptaron (ver error). canceled: cancelada.
"processing""pending""valid""rejected""canceled"uuid*|Folio fiscal que asigna el SAT (UUID del Timbre Fiscal Digital), en mayúsculas.
series*|Serie (Serie), hasta 25 caracteres. Cada serie lleva sus propios folios.
folio*|Folio (Folio). Fiscalisto asigna el siguiente de la serie; mande uno solo si debe ser ese.
date*|Fecha de emisión (Fecha), hora de la Ciudad de México.
customer*Cliente (Receptor): el id de uno de su catálogo (cus_…) o sus datos en un objeto.
use*|Uso del CFDI (UsoCFDI), clave de c_UsoCFDI. Por omisión G03, o S01 con régimen 616.
payment_form*|Forma de pago (FormaPago), clave de c_FormaPago: 01 efectivo, 03 transferencia, 04 tarjeta de crédito, 28 débito, 99 por definir… Obligatoria con PUE; con PPD es 99.
payment_method*|Método de pago (MetodoPago): PUE (una sola exhibición, por omisión) o PPD (en parcialidades o diferido, se cobra con complementos de pago).
currency*stringMoneda, clave ISO 4217 de c_Moneda (MXN, USD, EUR…). Por omisión MXN.
exchange_rate*|Tipo de cambio a pesos (TipoCambio). Obligatorio si la moneda no es MXN; use el del DOF del día anterior.
items*array<>Conceptos (Conceptos), al menos uno.
subtotal*|Suma de los importes antes de impuestos y descuentos (SubTotal).
discount*|Descuento (Descuento).
taxes*|Impuestos del comprobante, por tipo.
total*|Total en la moneda del comprobante (Total).
payment_status*|Si ya se cobró (Cuentas por cobrar): paid, partial (complementos de pago o notas de crédito por una parte) o unpaid. Una PUE está paid, salvo con paid_later hasta POST /v1/invoices/{id}/mark_paid. null si no es de ingreso o no está vigente.
amount_due*|Lo que falta por cobrar, en su moneda, o null.
amount_paid*|Lo cobrado: complementos de pago y notas de crédito vigentes, o todo si es PUE pagada. null si no aplica.
related*|CFDI relacionados (CfdiRelacionados): tipo de relación de c_TipoRelacion y los UUID.
payment?|Solo en un complemento de pago (type P).
payroll?Solo en un recibo de nómina (type N).
global?Solo en una factura global.
cancellation*|La cancelación, si se pidió: estado, motivo, sustituto y cuándo.
email*|El envío por correo: a quién, con copia a quién y cuándo (null si no se ha enviado).
error*|Por qué el SAT o el PAC no lo aceptaron: mensaje, código del SAT y texto original.
recurring_invoice*|La factura recurrente (rin_…) que la timbró sola, o null si se timbró con una llamada.
created_at*|Cuándo se creó, ISO 8601 con la hora de la Ciudad de México (-06:00).
metadata*Sus propios datos: hasta 50 llaves de 40 caracteres con valores de texto de hasta 500. No van al CFDI; vuelven en el objeto y en los webhooks.
warnings?array<string>Avisos que no impidieron timbrar (por ejemplo, el XML se guardará después).
email_error?stringPor qué no se pudo mandar el correo; el comprobante sí se timbró.
substitutes?La factura que esta sustituyó y si quedó cancelada.
advance_application?La aplicación del anticipo: método, nota de aplicación y su estado.
curl -X POST 'https://api.fiscalisto.com/v1/payments' \ -H 'Authorization: Bearer fk_test_…' \ -H 'Idempotency-Key: pedido-A-1042' \ -H 'Content-Type: application/json' \ -d '{ "payment_form": "03", "operation_number": "SPEI-2026102400123", "documents": [ { "invoice": "inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg", "amount": 2900 } ], "send_email": true}'{ "id": "inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg", "object": "invoice", "livemode": false, "issuer": "iss_OufpKqnrvx9p", "branch": null, "type": "I", "status": "valid", "uuid": "5F1E8C2A-3B7D-4C9E-A1B2-C3D4E5F60718", "series": null, "folio": "1", "date": "2026-10-24T10:15:42", "customer": { "tax_id": "ICV060329BY0", "legal_name": "INMOBILIARIA CVA", "tax_system": "601", "zip": "33826" }, "use": "I04", "payment_form": "03", "payment_method": "PUE", "currency": "MXN", "exchange_rate": null, "items": [ { "description": "Mensualidad", "product_key": "86121700", "unit_key": "E48", "unit_name": "Unidad de servicio", "sku": "MEN-1", "quantity": 2, "unit_price": 2500, "taxability": "02", "iva": "0.16" } ], "subtotal": 5000, "discount": 0, "taxes": { "iva": 800, "ieps": 0, "iva_withheld": 0, "isr_withheld": 0, "local_transferred": 0, "local_withheld": 0 }, "total": 5800, "payment_status": "paid", "amount_due": 0, "amount_paid": 5800, "related": null, "cancellation": null, "email": null, "error": null, "recurring_invoice": null, "created_at": "2026-10-24T10:15:42-06:00", "metadata": {}}Deshacer la conciliación POST
Vuelve a open, y sus facturas vuelven a deber. Si se pagó con un complemento vigente, cancélelo antes.
Timbrar una nota de crédito POST
Un egreso (tipo E) relacionado 01 (o 03, devolución) a una factura, con su IVA y retenciones en la misma proporción. amount es antes de impuestos.