Lotes de facturas

Un lote sirve para lo que se factura de golpe: las cuotas del mes de un condominio, las colegiaturas, las ventas del día de un marketplace. En lugar de mil solicitudes y sus límites, manda una.

curl https://api.fiscalisto.com/v1/invoice_batches \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Idempotency-Key: cuotas-2026-10" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cuotas de octubre",
    "invoices": [
      {
        "reference": "depto-101",
        "customer": "cus_OufpKqnrvx9p1",
        "payment_form": "03",
        "items": [{ "product": "prd_OufpKqnrvx9p1" }]
      },
      {
        "reference": "depto-102",
        "customer": { "tax_id": "ICV060329BY0", "legal_name": "INMOBILIARIA CVA", "tax_system": "601", "zip": "33826" },
        "payment_form": "03",
        "items": [{ "description": "Cuota de mantenimiento", "product_key": "80131500", "unit_price": 1500 }]
      }
    ]
  }'

Cada factura del lote es el mismo cuerpo de POST /v1/invoices, sin issuer (el lote es de un emisor), sin type ni global (son facturas de ingreso) y con reference en lugar de metadata: su identificador de esa factura, que vuelve en el resultado.

Cómo se timbraCopiar enlace a esta sección

1. Se revisan todas antes de empezar. Si una no pasa la revisión, la API responde 422 batch_invalid con param en la factura y el campo (invoices.3.items.0.unit_price) y no se timbra ninguna. Corríjala y mande el lote otra vez.
2. Se responde 202 de inmediato, con el lote en status: "processing".
3. Se timbran en segundo plano, a la velocidad que permite el PAC. Cada factura timbrada manda su invoice.stamped, como cualquier otra.
4. Al terminar llega invoice_batch.completed y el lote queda completed, con cuántas se timbraron (stamped) y cuántas no (failed).

{
  "id": "bat_OufpKqnrvx9p4hMdcoapAo5aaGJEme7mXj",
  "object": "invoice_batch",
  "status": "completed",
  "total": 2,
  "stamped": 1,
  "failed": 1,
  "processing": 0,
  "invoices": [
    { "index": 0, "reference": "depto-101", "status": "valid", "invoice": "inv_OufpKqnrvx9p0mn7VjQ6JlfipKAkHWstOK", "uuid": "DB494B07-D6DE-4F70-8ED0-C8B864FF8717", "total": 1740, "error": null },
    { "index": 1, "reference": "depto-102", "status": "failed", "invoice": null, "uuid": null, "total": 1740, "error": "El SAT no reconoce el nombre del cliente. Escríbalo exactamente como en su constancia de situación fiscal, en mayúsculas y sin «S.A. de C.V.» ni otro régimen de capital." }
  ]
}

Una factura puede fallar aunque pasó la revisión, si el SAT la rechaza (casi siempre por los datos del cliente). Esas no usan timbre: corríjalas y timbre cada una con POST /v1/invoices.

Consultar el avanceCopiar enlace a esta sección

GET /v1/invoice_batches/{id} dice cuántas van y el estado de cada una. Si no usa webhooks, consúltelo cada pocos segundos hasta que diga completed.

TimbresCopiar enlace a esta sección

Cada factura timbrada usa un timbre, al timbrarse. Antes de mandar un lote grande revise que le alcancen con GET /v1/balance: si se acaban a la mitad, las que faltan quedan failed con el motivo en error. Después de comprar, mándelas en otro lote, con otra Idempotency-Key.

RepetirloCopiar enlace a esta sección

Mandar el mismo lote con la misma Idempotency-Key contesta el lote que ya existe (202, como la primera vez, con idempotent-replayed: true), sin timbrar nada otra vez.