Facturas recurrentes
FISCALISTO / API / REFERENCIA
FISCALISTO / API / REFERENCIA
Una factura que el emisor timbra solo en cada fecha (cada interval meses en day_of_month, o cada interval semanas o días), a la hora que elija, con los timbres de su cuenta, y la manda al cliente si send_email. Cada una es una factura normal (invoice.stamped, con recurring_invoice) y nunca se timbra dos veces el mismo periodo. invoice es el cuerpo de POST /v1/invoices: se revisa ahora, con las mismas reglas.
bearerAuthAutorizaciónBearer <llave>Su llave secreta: fk_test_… en pruebas, fk_live_… en producción. Desarrolladores › Llaves.
Idempotency-Key?stringOpcional (los SDK la mandan solos). Si la respuesta se pierde, repita la solicitud con el mismo valor durante 24 horas: contesta lo mismo, con idempotent-replayed: true, y no lo hace dos veces (ni crea, ni manda correos, ni cobra).
1 <= length <= 255application/jsonissuer?stringEl emisor (iss_…). Puede omitirse si la llave o la cuenta tienen uno solo.
name*stringPara reconocerla: «Renta oficina 3», «Plan Pro de ACME».
1 <= length <= 80schedule*Cada cuánto y a qué hora se timbra.
invoice*La factura que se repite: el cuerpo de POST /v1/invoices, sin issuer, folio, date, global ni metadata. En description puede usar {mes}, {mes anterior}, {mes siguiente}, {año}, {año anterior}, {año siguiente} y {periodo}: cada factura los llena con su fecha. Como se escriben es como salen: {mes} «noviembre», {Mes} «Noviembre», {MES} «NOVIEMBRE».
send_email?booleanMandar cada factura al correo del cliente (customer.email o el del catálogo). Por omisión true.
catch_up?stringSi quedaron periodos sin timbrar (sin timbres, en pausa con su fecha pasada): all los timbra todos, cada uno con su mes; latest solo el más reciente. Por omisión all.
"all""latest"Correcto.
application/jsonUna factura que el emisor timbra solo, cada mes, semana o día.
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_…).
name*stringPara reconocerla.
status*stringactive (timbra en cada fecha) o paused.
"active""paused"schedule*Cada cuánto: frequency (monthly, weekly o daily), interval, day_of_month (con monthly; "last" es el último del mes), y la hora (hour, en time_zone) en que se timbra.
next_invoice_on*stringLa fecha (AAAA-MM-DD) de la siguiente factura.
last_invoiced_on*|La fecha del último periodo que timbró, o null si aún no timbra ninguna.
last_invoice*|La última factura (inv_…) que timbró, o null.
last_error*|Por qué no se pudo timbrar la última vez (sin timbres, el cliente borrado, el SAT la rechazó…), o null. Se vuelve a intentar a la siguiente hora del día siguiente; también llega recurring_invoice.failed.
send_email*booleanSi cada factura se manda al correo del cliente.
catch_up*stringSi quedaron periodos sin timbrar: all los timbra todos, latest solo el más reciente.
"all""latest"customer*A quién se factura.
currency*stringLa moneda de la factura.
items*array<>Los conceptos, con description tal como se guardó ({mes}, {año}… se llenan en cada factura).
total*|El total de cada factura con los precios de hoy.
created_at*|Cuándo se creó.
curl -X POST 'https://api.fiscalisto.com/v1/recurring_invoices' \ -H 'Authorization: Bearer fk_test_…' \ -H 'Idempotency-Key: 8f14e45f-ceea-467a-9575-6a1b0e5f3c21' \ -H 'Content-Type: application/json' \ -d '{ "name": "Renta oficina 3", "schedule": { "frequency": "monthly", "day_of_month": 1, "hour": 7 }, "invoice": { "customer": { "tax_id": "ICV060329BY0", "legal_name": "INMOBILIARIA CVA", "tax_system": "601", "zip": "33826", "email": "pagos@cva.example" }, "payment_form": "03", "items": [ { "description": "Renta de oficina de {mes} {año}", "product_key": "80131500", "unit_price": 15000 } ] }}'{ "id": "rin_OufpKqnrvx9p7Hq2mZr1XyT5uBcW8sKdLx", "object": "recurring_invoice", "livemode": false, "issuer": "iss_OufpKqnrvx9p", "name": "Renta oficina 3", "status": "active", "schedule": { "frequency": "monthly", "interval": 1, "day_of_month": 1, "hour": 7, "time_zone": "America/Mexico_City" }, "next_invoice_on": "2026-11-01", "last_invoiced_on": "2026-10-01", "last_invoice": "inv_OufpKqnrvx9p6hW1yQbT3mZr8sKdLx0VeN", "last_error": null, "send_email": true, "catch_up": "all", "customer": { "tax_id": "ICV060329BY0", "legal_name": "INMOBILIARIA CVA" }, "currency": "MXN", "items": [ { "description": "Renta de oficina de {mes} {año}", "product_key": "80131500", "quantity": 1, "unit_key": "E48", "unit_price": 15000 } ], "total": 17400, "created_at": "2026-09-28T11:02:14-06:00"}