Reportes a Excel

Conceptos Generales

Los dos reportes principales del panel de Zenrise —Facturas y Estado de cuenta— también se pueden generar directamente contra la API, sin entrar a la web. Son exactamente los mismos endpoints que usa nuestro panel, así que el archivo que vas a recibir es idéntico al que descargás desde ahí.

Ambos reportes:

• Se devuelven como archivo binario en el body de la respuesta (no como un JSON con una URL).
• Están acotados a la organización dueña del token. No hace falta enviar el id de tu organización ni es posible pedir el reporte de otra.
• Requieren autenticación, igual que el resto de la API.

Importante! Estos endpoints están pensados para generar reportes, no para sincronizar datos. Si necesitás procesar la información dentro de tu sistema te recomendamos usar los endpoints de consulta, que devuelven JSON paginado.

Cómo se devuelve el archivo

La respuesta exitosa es el archivo en sí, con estos headers:

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment;filename=Reporte-de-facturas-2026-07-28.xlsx

El nombre sugerido del archivo viaja en el header Content-Disposition. Exponemos ese header vía CORS, así que también podés leerlo desde el navegador.

Importante! Si tu cliente HTTP interpreta las respuestas como JSON por defecto, tenés que pedir la respuesta como binario (responseType: 'arraybuffer' en axios, arrayBuffer() en fetch). Si no lo hacés, el Excel se descarga corrupto.

---

Reporte de Facturas

Es el mismo archivo que genera el botón Descargar excel de la pantalla de Facturas.

URL: /v1/excel-writer/invoices

Método: GET

Requiere Auth: Sí, ver Autenticación

Query Params:

Parámetro	Tipo	Requerido	Descripción
startDate	date	Sí	Fecha desde, en formato AAAA-MM-DD. Filtra por fecha de la factura, inclusive.
endDate	date	Sí	Fecha hasta, en formato AAAA-MM-DD. Filtra por fecha de la factura, inclusive.
search	string	No	Texto libre de búsqueda.
status	string	No	Estado de la factura. Ver tabla más abajo.
sortBy	string	No	Campo de ordenamiento. Por defecto id.
sortDirection	string	No	ASC o DESC. Por defecto ASC.
email	string	Depende	Email al que enviamos el reporte. Sólo aplica en modo envío por email (ver más abajo).

Ejemplo:

curl -OJ -G 'https://api.zenrise.io/v1/excel-writer/invoices' \
  -H 'Authorization: Bearer <JWT-TOKEN>' \
  -d 'startDate=2026-07-01' \
  -d 'endDate=2026-07-31' \
  -d 'sortBy=firstDueDate' \
  -d 'sortDirection=DESC'

Detalles importantes de los parámetros:

startDate y endDate filtran por la fecha de la factura y toman ambos extremos del rango. Formalmente son opcionales, pero si no los enviás no aplicamos ningún filtro de fechas y el reporte sale con todo el historial de tu organización, algo que en general no es lo que buscás. Te recomendamos pedir rangos de hasta un mes, que es el rango que usa el panel por defecto.

search busca coincidencias parciales en la descripción de la factura, en su referencia externa, en el nombre completo del contacto y en el nombre de la organización. Si el valor es numérico, también busca por id de factura.

status acepta uno de estos valores:

Valor	Descripción
pendingPayment	Pendiente de pago (incluye facturas con intento de pago rechazado).
partiallyPaid	Parcialmente pagada.
pendingAccreditation	Pagada y pendiente de acreditación.
acreditedInAccount	Pagada y acreditada en tu cuenta.
refund	Devolución: factura anulada con su pago anulado.
chargeBack	Contracargo: factura anulada por un contracargo de la tarjeta.

Importante! En este endpoint status admite un único valor. Si mandás varios separados por coma el filtro se ignora por completo y el reporte sale con todos los estados. Si necesitás un subconjunto de estados, pedí un reporte por estado y unificá los archivos de tu lado.

sortBy admite id, amountDue, amountPaid, paymentPaymentMethod, firstDueDate, contactFullName y lastPaymentDate. Cualquier otro valor se ignora y ordenamos por id.

El reporte no admite filtro por medio de pago: el filtro de medios de pago del panel aplica al listado en pantalla, no al Excel.

Columnas del reporte:

#	Columna	Detalle
1	Id	Id de la factura en Zenrise.
2	Nombre completo	Nombre completo del contacto.
3	Email	Email del contacto.
4	Descripción	Descripción de la factura.
5	Referencia externa Contacto	externalReference del contacto.
6	Documento Contacto	Número de documento del contacto.
7	Referencia externa Factura	externalReference de la factura.
8	Monto a pagar
9	Monto pagado
10	Medio de Pago	Medio de pago de los pagos asociados.
11	Fecha de creación
12	Primera fecha de vencimiento
13	Segunda fecha de vencimiento
14	Fechas de pago	Fecha del primer pago registrado.
15	Fecha de acreditación
16	Fecha estimada de Transferencia	Fecha estimada de acreditación de cada pago.
17	Nombre de grupos	Grupos del contacto, separados por doble barra vertical.
18	Estado	Estado de la factura, ver Estado de facturas.
19	Link de factura	Link al comprobante.
20	Número de cuota	Sólo se completa en organizaciones con cobro en cuotas.
21	Error	Motivo del último error de cobro, cuando aplica.
22	Fecha de error
23	Fecha última actualización
24	Punto Venta Afip	Sólo si la factura fue emitida por AFIP.
25	Número Comprobante Afip	Sólo si la factura fue emitida por AFIP.
26	Fecha Comprobante Afip	Sólo si la factura fue emitida por AFIP.
27	ID Suscripción	Si la factura fue generada por una suscripción.
28	ID Contacto
29	Link a cobro con tarjeta	Sólo en organizaciones que tienen habilitada esta columna.
30	Comisión	Comisión total cobrada por Zenrise sobre los pagos de esa factura.

Importante! Los encabezados del archivo se escriben con espacios al inicio y al final, y algunos arrastran erratas históricas (por ejemplo Fecha de accreditación). Si procesás el Excel de forma automática, te recomendamos normalizar los nombres de las columnas o trabajar por posición.

Descarga directa o envío por email

Este endpoint tiene dos modos de entrega, según cómo esté configurada tu organización:

Modo	Cuándo aplica	Qué devuelve
Descarga directa	Configuración por defecto.	200 con el archivo .xlsx en el body.
Envío por email	Organizaciones con el exportador habilitado.	200 con body vacío. El reporte llega por email en unos minutos.

Habilitamos el exportador en organizaciones con mucho volumen de facturas, porque generar el archivo en el momento tardaría demasiado. Si es tu caso:

• El parámetro email pasa a ser obligatorio. Si no lo enviás la respuesta es 400 con el mensaje email is required.
• La respuesta 200 sólo confirma que tomamos el pedido; el archivo se genera después y llega por email como uno o más links de descarga (ReporteFacturas_<organización>_Desde<fecha>_Hasta<fecha>-Parte1.xlsx, -Parte2.xlsx, …).
• En este modo sólo se aplican startDate y endDate. Los filtros search, status, sortBy y sortDirection se ignoran.

Importante! Si no sabés en qué modo está tu organización, hacé una prueba con un rango chico: si la respuesta viene con body vacío en vez del archivo, tu organización usa el envío por email.

---

Reporte de Estado de cuenta

Es el mismo archivo que genera Exportar movimientos de cuenta en la pantalla de Movimientos. Lista los movimientos de tu cuenta Zenrise (cobranzas, extracciones, comisiones, impuestos, contracargos) con el saldo acumulado.

URL: /v1/excel-writer/balance-transaction-organization

Método: GET

Requiere Auth: Sí, ver Autenticación

Query Params:

Parámetro	Tipo	Requerido	Descripción
startDate	date	Sí	Fecha desde, en formato AAAA-MM-DD, inclusive.
endDate	date	Sí	Fecha hasta, en formato AAAA-MM-DD, inclusive.
useExporter	boolean	No	Por defecto true. Ver detalle más abajo.
sortBy	string	No	Se acepta por compatibilidad, no modifica el orden del reporte.
sortDirection	string	No	Se acepta por compatibilidad, no modifica el orden del reporte.

Ejemplo:

curl -OJ -G 'https://api.zenrise.io/v1/excel-writer/balance-transaction-organization' \
  -H 'Authorization: Bearer <JWT-TOKEN>' \
  -d 'startDate=2026-07-01' \
  -d 'endDate=2026-07-31'

Detalles importantes de los parámetros:

startDate y endDate son obligatorios en este reporte. Si falta alguno la request falla con 500.

useExporter define quién genera el archivo. Con el valor por defecto true lo genera nuestro servicio de exportación, preparado para volúmenes grandes; es el que usa el panel y el que te recomendamos. Con useExporter=false lo genera la API en el momento: es más lento, puede cortar por timeout en rangos amplios, filtra los movimientos por fecha de acreditación y agrega una columna extra de Fecha de Pago.

sortBy y sortDirection no tienen efecto: los movimientos siempre salen ordenados por id de movimiento ascendente, que es el orden necesario para que el saldo acumulado tenga sentido.

Columnas del reporte:

#	Columna	Detalle
1	Tipo de movimiento	Cobranza, extracción, comisión, impuesto, contracargo, etc.
2	Fecha Movimiento
3	ID movimiento	Id del movimiento en tu cuenta.
4	ID Pago/Extraccion	Id del pago o de la transferencia que originó el movimiento.
5	Monto Total	Monto bruto del movimiento.
6	Comision Cobrada	Comisión de Zenrise sobre ese movimiento.
7	Neto	Monto que impacta en tu saldo (Monto Total menos comisión).
8	Descripcion Movimiento
9	Id Factura	Factura asociada, si el movimiento vino de una cobranza.
10	Monto Factura
11	Descripcion	Descripción de la factura asociada.
12	Nombre del Contacto
13	Datos cuenta extraccion (Titular - Documento - Cbu)	Sólo para extracciones y transferencias.
14	Documento	Documento del contacto pagador.
15	Saldo Acumulado	Saldo de la cuenta después de cada movimiento.
16	Fecha de Pago	Sólo se incluye cuando pedís el reporte con useExporter=false.

Importante! La columna Saldo Acumulado arranca del saldo que tenía tu cuenta justo antes del primer movimiento del rango, así el reporte cierra contra tu saldo real y no contra cero.

En rangos con un volumen de movimientos muy alto el contenido del archivo puede venir en formato CSV aunque la extensión sea .xlsx. Es un archivo de texto separado por comas y se abre igual desde Excel.

El mismo reporte en PDF

Cambiando el endpoint obtenés el mismo estado de cuenta en PDF, con los mismos parámetros:

URL: /v1/excel-writer/balance-transaction-organization-pdf

Método: GET

Requiere Auth: Sí, ver Autenticación

Envío por email

Las organizaciones con el exportador habilitado reciben el estado de cuenta por email, igual que el reporte de facturas:

URL: /v1/excel-writer/balance-transaction

Método: GET

Requiere Auth: Sí, ver Autenticación

Query Params: startDate, endDate y email (obligatorio).

La respuesta es 200 con body vacío y el reporte llega por email en unos minutos. Si tu organización no tiene el exportador habilitado, usá el endpoint de descarga directa.

---

Errores comunes

Código	Cuándo pasa
400	Falta email y tu organización está configurada para recibir el reporte por email.
401	Token vencido o ausente. Recordá que el token dura una hora, ver Autenticación.
500	Faltan startDate o endDate en el reporte de estado de cuenta, o el rango pedido es tan amplio que la generación no terminó a tiempo.

Ejemplo completo en Node.js

Descarga del reporte de facturas guardando el archivo con el nombre que devuelve la API:

const fs = require('fs');

async function descargarReporteDeFacturas(token, startDate, endDate) {
  const url = new URL('https://api.zenrise.io/v1/excel-writer/invoices');
  url.searchParams.set('startDate', startDate);
  url.searchParams.set('endDate', endDate);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (!response.ok) {
    throw new Error(`La API respondió ${response.status}`);
  }

  const disposition = response.headers.get('content-disposition') || '';
  const fileName = disposition.split('filename=')[1] || `reporte-${startDate}.xlsx`;

  const buffer = Buffer.from(await response.arrayBuffer());

  if (buffer.length === 0) {
    // Tu organización recibe los reportes por email: revisá tu casilla en unos minutos.
    return null;
  }

  fs.writeFileSync(fileName, buffer);
  return fileName;
}