FISCALISTO / API / REFERENCIA
Timbrar un anticipo
La factura del anticipo: un concepto «Anticipo del bien o servicio» (84111506, ACT). amount es lo que pagó el cliente con IVA.
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.
customer*|Cliente (Receptor): el id de uno de su catálogo (cus_…) o sus datos en un objeto.
use?stringUso del CFDI (UsoCFDI), clave de c_UsoCFDI. Por omisión G03, o S01 con régimen 616.
amount*numberLo que pagó el cliente, con IVA incluido.
0 < valueiva?stringTasa de IVA trasladado: 0.16 (por omisión), 0.08 (región fronteriza), 0 o exento.
"0.16""0""0.16""0.08""exento"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}$currency?stringMoneda, clave ISO 4217 de c_Moneda (MXN, USD, EUR…). Por omisión MXN.
3 <= length <= 3exchange_rate?numberTipo de cambio a pesos (TipoCambio). Obligatorio si la moneda no es MXN; use el del DOF del día anterior.
0 < valueseries?stringSerie (Serie), hasta 25 caracteres. Cada serie lleva sus propios folios.
length <= 25notes?stringObservaciones que aparecen en el PDF (no van en el XML).
length <= 1000send_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_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.
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/advances' \ -H 'Authorization: Bearer fk_test_…' \ -H 'Idempotency-Key: pedido-A-1042' \ -H 'Content-Type: application/json' \ -d '{ "customer": { "tax_id": "ICV060329BY0", "legal_name": "INMOBILIARIA CVA", "tax_system": "601", "zip": "33826", "email": "pagos@cva.example" }, "amount": 1160, "payment_form": "03"}'{ "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": {}}Listar anticipos sin aplicar GET
Los anticipos timbrados que todavía no se aplican a una factura, con lo que queda de cada uno. Filtre por customer para los de un cliente.
Aplicar un anticipo POST
Timbra la factura de lo vendido (el cuerpo de POST /v1/invoices) relacionada 07 al anticipo. Con method egreso, también la nota de aplicación. La misma Idempotency-Key continúa donde se quedó.