Descargas del SAT

Con la descarga masiva del SAT usted trae todas las facturas que un emisor recibió (sus gastos, de cualquier proveedor) o emitió (aunque no las haya hecho con Fiscalisto), con su XML. Sirve para la contabilidad, para conciliar pagos o para revisar a los proveedores contra las listas del SAT. En producción usan timbres según cuántas facturas traen; en pruebas no cuestan.

El SAT tarda de unos minutos a unas horas en preparar cada descarga. Usted la pide, sigue con lo suyo y le llega sat_download.completed cuando las facturas ya están.

En pruebas y en producciónCopiar enlace a esta sección

• En producción se le pregunta al SAT con la e.firma del emisor, que usted guarda una vez (abajo).
• En pruebas el SAT no tiene un ambiente de pruebas para esto, así que no se le pregunta: la descarga termina al instante con facturas de ejemplo entre el emisor y los RFC de prueba del SAT, con su XML y su evento. Pedir lo mismo otra vez trae las mismas facturas, sin duplicarlas. No necesita e.firma.

Guardar la e.firma del emisorCopiar enlace a esta sección

En producción, mande la e.firma (el .cer y el .key en base64 y su contraseña) con keep_for_downloads: true. Se revisa que sea una e.firma vigente de ese RFC y se guarda cifrada, como en la app. Si el emisor aún no firmó el contrato con el PAC y ya tiene su CSD, la misma llamada lo firma.

curl https://api.fiscalisto.com/v1/issuers/iss_OufpKqnrvx9p/efirma \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"cer\": \"$(base64 < efirma.cer | tr -d '\n')\",
    \"key\": \"$(base64 < efirma.key | tr -d '\n')\",
    \"password\": \"$EFIRMA_PASSWORD\",
    \"keep_for_downloads\": true
  }"

El emisor trae sat_downloads.available: true y cuándo vence su e.firma en sat_downloads.efirma_expires_at. Para borrarla: DELETE /v1/issuers/{id}/efirma. El emisor sigue timbrando; solo deja de poder pedir descargas.

Pedir una descargaCopiar enlace a esta sección

curl https://api.fiscalisto.com/v1/sat_downloads \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "direction": "received", "from": "2026-09-01", "to": "2026-09-30" }'

Contesta 202 con la descarga (sdl_…) en status: "processing" (en pruebas ya viene completed):

{
  "id": "sdl_OufpKqnrvx9p3n8vQd2LkW7mZr1XyT5uBc",
  "object": "sat_download",
  "livemode": true,
  "issuer": "iss_OufpKqnrvx9p",
  "direction": "received",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "type": null,
  "counterparty_tax_id": null,
  "uuid": null,
  "status": "processing",
  "new_invoices": null,
  "error": null,
  "created_at": "2026-10-24T10:20:00-06:00",
  "completed_at": null
}

Las recibidas llegan vigentes: el SAT solo entrega el XML de una factura recibida mientras no esté cancelada.

Cuando terminaCopiar enlace a esta sección

Llega el evento sat_download.completed con la descarga y new_invoices, cuántas facturas nuevas trajo (las que ya tenía no se cuentan dos veces). Si el SAT no pudo, llega sat_download.failed con el motivo en error, por ejemplo una e.firma vencida. También puede consultarla con GET /v1/sat_downloads/{id} o listarlas con GET /v1/sat_downloads.

El SAT limita cuántas veces se puede pedir exactamente lo mismo (el mismo periodo con los mismos filtros). Si se agotan, la respuesta es sat_request_rejected: pida un periodo un poco distinto.

Las facturasCopiar enlace a esta sección

curl "https://api.fiscalisto.com/v1/sat_invoices?direction=received&date_gte=2026-09-01&limit=20" \
  -H "Authorization: Bearer $FISCALISTO_API_KEY"

Cada factura (sat_…) trae su folio fiscal, quién la emitió (issued_by) y a quién (issued_to), los importes, los impuestos trasladados y retenidos, y su estado en el SAT (sat_status). Se filtran por direction, type, counterparty_tax_id, date_gte y date_lte, de la más reciente a la más antigua, con la paginación de siempre. El XML, tal como lo entregó el SAT, está en GET /v1/sat_invoices/{id}/xml.

LímitesCopiar enlace a esta sección

Hasta 300 descargas al día por cuenta en producción y 50 en pruebas. En producción, pedir una usa un timbre, que alcanza para los primeros 100 CFDI (si el SAT la rechaza, el timbre regresa). Cuando el SAT dice cuántos tiene, cada 100 más, o los que sobren, usan otro timbre antes de descargarlos: 1,250 CFDI son 13 timbres. Si a su cuenta no le alcanzan, la descarga termina en failed (evento sat_download.failed), sin descargar nada, y el timbre de la solicitud no regresa. En pruebas no cuestan. Vea Límites.

Pedir otra vez una descarga igual (mismo emisor, fechas y filtros) mientras el SAT todavía trabaja en ella contesta esa misma descarga, sin otro timbre: así un reintento después de un timeout no gasta las pocas solicitudes idénticas que acepta el SAT. Cuando ya terminó, una igual es una descarga nueva.