FISCALISTO / API / REFERENCIA
Cancelar una factura POST
Pide la cancelación al SAT. Si el cliente debe aceptarla queda en pending (escuche invoice.canceled o invoice.cancellation_rejected). No usa timbres.
Marcar pagada POST
Una factura PUE timbrada con paid_later (o marcada por cobrar) ya se pagó: queda paid y llega invoice.paid. Una PPD se paga con su complemento de pago (POST /v1/payments).
Timbra la factura corregida (el mismo cuerpo que POST /v1/invoices, relacionada 04) y cancela la anterior con motivo 01.
bearerAuthAutorizaciónBearer <llave>Su llave secreta: fk_test_… en pruebas, fk_live_… en producción. Desarrolladores › Llaves.
id*stringEl id del objeto.
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/jsonUna factura (CFDI 4.0). Un campo que no existe se rechaza con parameter_unknown, nunca se ignora.
issuer?stringEmisor (iss_…). Si la llave tiene un solo emisor o la cuenta tiene uno solo, puede omitirse.
^iss_branch?stringSucursal (brn_…) desde donde se factura: su código postal va en LugarExpedicion, su dirección en el PDF y, si las tiene, sus series. Sin ella, el domicilio fiscal del emisor (la Matriz).
^brn_warehouse?stringAlmacén (whs_…) de donde salen sus productos con track_stock. Por omisión, el de su sucursal (o el de la Matriz).
^whs_customer*|Cliente (Receptor): el id de uno de su catálogo (cus_…) o sus datos en un objeto.
items*array<>Conceptos (Conceptos), al menos uno.
1 <= items <= 200type?stringI ingreso (por omisión; con global, factura global) o T traslado. Notas de crédito: POST /v1/credit_notes. Pagos: POST /v1/payments.
"I""I""T"carta_porte?Complemento Carta Porte 3.1 (traslado de mercancías).
ine?Complemento INE (procesos electorales).
leyendas?array<>Complemento de leyendas fiscales.
items <= 10donation?Complemento de donatarias.
local_taxes?array<>Impuestos locales (complemento implocal): traslados y retenciones estatales.
items <= 20export?stringExportación (Exportacion), c_Exportacion: 01 no aplica (por omisión), 02 definitiva…
"01""02""03""04"comercio_exterior?Complemento de comercio exterior 2.0.
global?Factura global a público en general (InformacionGlobal): periodicidad, meses y año.
use?stringUso del CFDI (UsoCFDI), clave de c_UsoCFDI. Por omisión G03, o S01 con régimen 616.
^[A-Z]{1,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}$payment_method?stringMétodo de pago (MetodoPago): PUE (una sola exhibición, por omisión) o PPD (en parcialidades o diferido, se cobra con complementos de pago).
"PUE""PPD"paid_later?booleanCon PUE: true si aún no le pagan («Por cobrar» en la app) aunque se pagará este mes.
currency?stringMoneda, clave ISO 4217 de c_Moneda (MXN, USD, EUR…). Por omisión MXN.
3 <= length <= 3series?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 <= 1000pdf_language?stringIdioma del PDF: es (por omisión) o en.
"es""en""bi"addenda?Addenda del receptor (Walmart, Soriana…), con sus propios campos.
related?CFDI relacionados (CfdiRelacionados): tipo de relación de c_TipoRelacion y los UUID.
exchange_rate?numberTipo de cambio a pesos (TipoCambio). Obligatorio si la moneda no es MXN; use el del DOF del día anterior.
0 < value <= 1000000folio?integerFolio (Folio). Fiscalisto asigna el siguiente de la serie; mande uno solo si debe ser ese.
1 <= value <= 2000000000continue_sequence?booleanCon un folio elegido: true para que los siguientes sigan desde ese número.
date?stringFecha de emisión (Fecha) si no es ahora, AAAA-MM-DDTHH:MM:SS hora de la Ciudad de México: hasta 72 horas antes.
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$send_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.
falseemail_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/jsonUn 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/invoices/string/substitute' \ -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" }, "payment_form": "03", "items": [ { "description": "Mensualidad", "product_key": "86121700", "quantity": 2, "unit_price": 2400 } ], "send_email": true, "metadata": { "pedido": "A-1042" }}'{ "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": {}}