# Relatórios (/docs/pix-processamento/endpoints/reports)



Os endpoints de **Relatórios** cobrem tudo que envolve **leitura histórica** das transações. Use a listagem ao vivo para dashboards e a geração assíncrona em CSV para BI/auditoria de períodos grandes.

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/endpoints/reports/get_user_transactions" title="Listar transações" method="GET" path="/user/transactions" />

  <QuickLink href="/docs/pix-processamento/endpoints/reports/get_user_transaction_by_id" title="Detalhe da transação" method="GET" path="/user/transactions/{id}" />

  <QuickLink href="/docs/pix-processamento/endpoints/reports/post_user_report" title="Gerar relatório" method="POST" path="/user/report" />

  <QuickLink href="/docs/pix-processamento/endpoints/reports/list_user_reports" title="Listar relatórios" method="GET" path="/user/reports" />

  <QuickLink href="/docs/pix-processamento/endpoints/reports/get_user_report" title="Status do relatório" method="GET" path="/user/report/{id}" />

  <QuickLink href="/docs/pix-processamento/endpoints/reports/download_user_report" title="Baixar relatório" method="POST" path="/user/report/{id}/download" />
</QuickLinks>

## Quando usar cada um [#quando-usar-cada-um]

| Cenário                                | Endpoint                                                                                              |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Tela de transações no dashboard        | [`GET /user/transactions`](/docs/pix-processamento/endpoints/reports/get_user_transactions)           |
| Detalhe de uma transação específica    | [`GET /user/transactions/{id}`](/docs/pix-processamento/endpoints/reports/get_user_transaction_by_id) |
| Relatório de período grande (mês, ano) | [`POST /user/report`](/docs/pix-processamento/endpoints/reports/post_user_report)                     |
| Listar relatórios solicitados          | [`GET /user/reports`](/docs/pix-processamento/endpoints/reports/list_user_reports)                    |
| Verificar se o relatório terminou      | [`GET /user/report/{id}`](/docs/pix-processamento/endpoints/reports/get_user_report)                  |
| Baixar o CSV gerado                    | [`POST /user/report/{id}/download`](/docs/pix-processamento/endpoints/reports/download_user_report)   |

## Listagem vs relatório assíncrono [#listagem-vs-relatório-assíncrono]

| Cenário                     | Recomendado                          |
| --------------------------- | ------------------------------------ |
| Dashboard, \< 10k registros | `GET /user/transactions` paginado    |
| Conciliação diária          | `GET /user/transactions` paginado    |
| Mês ou ano completo         | `POST /user/report` (CSV assíncrono) |
| BI / Data Warehouse         | `POST /user/report` agendado         |

## Exemplos [#exemplos]

<Accordions type="single">
  <Accordion title="GET /user/transactions, filtrar por período e status">
    ```bash
    curl "https://api.payzu.processamento.com/v1/user/transactions?dateFrom=2025-08-01&dateTo=2025-08-31&status=COMPLETED&page=1&limit=100" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json"
    ```
  </Accordion>

  <Accordion title="POST /user/report, gerar CSV do mês">
    ```bash
    curl -X POST https://api.payzu.processamento.com/v1/user/report \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "dateFrom": "2025-08-01",
        "dateTo": "2025-08-31",
        "status": ["COMPLETED"],
        "type": ["DEPOSIT", "WITHDRAW"]
      }'
    ```
  </Accordion>

  <Accordion title="POST /user/report/{id}/download, pegar URL assinada">
    ```bash
    curl -X POST "https://api.payzu.processamento.com/v1/user/report/JOB_ID/download" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json"
    ```
  </Accordion>
</Accordions>

## Fluxo do relatório assíncrono [#fluxo-do-relatório-assíncrono]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;POST /user/report&#x22;] --> B[&#x22;Job criado PENDING&#x22;]
  B --> C[&#x22;Processamento&#x22;]
  C --> D[&#x22;READY&#x22;]
  D --> E[&#x22;POST /report/{id}/download&#x22;]
  E --> F[&#x22;URL assinada (CSV)&#x22;]

  click A &#x22;/docs/pix-processamento/endpoints/reports/post_user_report&#x22; &#x22;POST /user/report&#x22;
  click D &#x22;/docs/pix-processamento/endpoints/reports/get_user_report&#x22; &#x22;GET /user/report/{id}&#x22;
  click E &#x22;/docs/pix-processamento/endpoints/reports/download_user_report&#x22; &#x22;Download&#x22;

  style A fill:#f59e0b,stroke:#d97706,color:#ffffff
  style D fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

## Tutoriais e boas práticas [#tutoriais-e-boas-práticas]

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/tutoriais/reconciliation" title="Tutorial: Conciliação" />

  <QuickLink href="/docs/pix-processamento/best-practices/pagination" title="Paginação" />

  <QuickLink href="/docs/pix-processamento/best-practices/multi-tenant" title="Multi-tenant" />
</QuickLinks>