---
title: "Generar Report"
method: POST
path: "/reports/{entity}"
tags: ["Reports"]
---

# Generar Report

`POST /reports/{entity}`

## Request

- Base URL: `https://api.trytoku.com`
- URL: `https://api.trytoku.com/reports/{entity}`
- Auth: API key in header `x-api-key`

Genera el reporte de la entidad indicada y devuelve las URLs firmadas para descargarlo.

Aplica los filtros del payload, exporta el resultado en el formato pedido (`xlsx` por defecto o `csv`) y deja los archivos en almacenamiento. La respuesta trae el identificador de la ejecución del reporte, la URL del archivo principal, las URLs de todos los archivos generados y, para las entidades que lo ofrecen, un resumen agregado del contenido.

Si el payload incluye `user_email` o `external_emails`, además se envía el reporte por correo a esas direcciones. Cuando la consulta no arroja registros la operación responde `204` sin cuerpo y, de haber destinatarios, les avisa por correo que el reporte quedó vacío.

Con `export_format=csv` y varias hojas, `csv_export_strategy` decide la forma de entrega: `zip` empaqueta todas las hojas en un archivo, `single_sheet` exporta solo la hoja de `csv_target_sheet`, e `individual` genera un CSV por hoja y es incompatible con el envío por correo. El identificador de la ejecución permite consultar después su estado en `/report-executions`.

## Path parameters

- `entity` 'bank_account_verification' | 'billing' | 'campaign' | 'card_verification' | 'customer' | 'customer_portal_event' | 'interaction_event' | 'invoice' | 'message' | 'payment' | 'payment_v2' | 'payment_intent' | 'payment_method' | 'payout' | 'payout_v2' | 'subscription' | 'ticket' | 'payment_method_inscription_intent' | 'pac_inscription_intent' | 'payout_additional' | 'campaign_customer' | 'campaign_invoice' | 'transfer_cl_activation' | 'electronic_signature_document' | 'chargeback' | 'chargeback_v2' | 'temporary_collection_file' | 'recipient_verification' | 'conversations_ai_agent' | 'forum_notification' | 'payout_disbursement' | 'beneficiary_account' | 'payout_batch' | 'reconciliation', required: Conjunto de datos que se exporta. Cada valor apunta a un reporte distinto, con sus propias columnas y hojas, así que es lo que determina la forma del archivo resultante. Es un catálogo que crece al publicar reportes nuevos, y no todos los valores están disponibles para toda organización: algunos dependen de sus permisos y otros exigen parámetros adicionales. Los valores terminados en `_v2` no son otro formato del mismo reporte, sino una versión que lee un modelo de datos más nuevo, con columnas y hojas distintas.

## Request body

- ModelsReportsGenerateReportRequest
  - `csv_delimiter` string: Single ASCII field delimiter for CSV export. Default: semicolon.
  - `csv_export_strategy` 'zip' | 'individual' | 'single_sheet': Cómo se entregan las hojas de un reporte exportado a CSV: `zip` las empaqueta en un archivo comprimido, con un CSV por hoja; `individual` entrega un CSV suelto por hoja, cada uno con su propia URL; y `single_sheet` entrega un único CSV con la hoja indicada en `csv_target_sheet`. Solo tiene efecto cuando el formato de exportación es `csv`.
  - `csv_target_sheet` string
  - `custom_params` object
  - `date_range` 'CURRENT_DAY' | 'PREVIOUS_DAY' | 'LAST_WEEK' | 'LAST_7DAYS' | 'CURRENT_MONTH' | 'LAST_MONTH' | 'LAST_30DAYS' | 'LAST_3MONTHS' | 'LAST_12MONTHS': Rango de fechas relativo a un día de referencia: hoy, salvo que la ejecución indique otro. Los dos extremos son inclusivos.
  - `exclude` string[]
  - `export_format` 'xlsx' | 'csv': Formato del archivo que se genera: `xlsx` entrega un solo libro, con una hoja por cada hoja del reporte, y `csv` entrega archivos planos, cuya cantidad y empaquetado dependen de `csv_export_strategy`.
  - `external_emails` string[]: Additional email addresses to receive the report (optional). Combined with user_email for notification.
  - `filters` ReportFilterRequest[]
    - `column_name` string, required
    - `criteria` 'lt' | 'gt' | 'le' | 'ge' | 'eq' | 'neq' | 'in' | 'not_in' | 'is', required: Operador con que un filtro compara una columna del reporte contra el valor entregado: `lt` y `gt` son menor y mayor estrictos, `le` y `ge` los mismos pero incluyendo la igualdad, `eq` y `neq` son igual y distinto, `in` y `not_in` esperan una lista y filtran por pertenecer o no a ella, e `is` compara contra un valor exacto.
    - `table_name` string
    - `value` unknown
  - `header_metadata` object
  - `include_metadata_header` boolean
  - `include_soft_deleted` boolean
  - `timezone` string
  - `timezone_offset` integer
  - `user_email` string

## Response `200`

Successful Response

- GenerateReportResponse
  - `report_execution_id` string, required
  - `summary` object: Optional aggregate summary for the report (e.g. invoice-outcome counts). None for entities that don't provide one.
  - `url` string, required
  - `urls` string[]

## Other responses

- `401`: Faltan las credenciales o son inválidas.
- `403`: No tienes acceso a este recurso.
- `404`: El recurso solicitado no existe.
- `422`: El cuerpo de la petición no pasó la validación.
- `429`: Se superó el límite de peticiones permitidas.

## Changes

- **2026-11-03** `a6ef070075b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/trytoku/apis/toku-api/changes/reports/:entity/post.md)

---

[API](https://skmtc.dev/trytoku/apis/toku-api.md) - [All operations](https://skmtc.dev/trytoku/apis/toku-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trytoku/apis/toku-api/revisions/a6ef070075b1?raw)