> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Início rápido da API do Reporter

<Tip>
  **Este guia é destinado a desenvolvedores.** Se você está procurando uma visão geral de nível de negócio sobre o que o Reporter faz, veja [O que é o Reporter?](/pt/reporter/what-is-reporter).
</Tip>

Coloque o Reporter em funcionamento em minutos. Este guia percorre o caminho completo, desde o upload da sua primeira template até o download de um relatório gerado.

## Antes de começar

***

Você precisa de:

* Uma instância do Reporter em execução
* Um token de autenticação válido (se o Access Manager estiver habilitado)
* Um arquivo de template `.tpl` pronto para upload

Todos os exemplos usam `cURL`. Substitua `$TOKEN` pelo seu token de autenticação e `https://reporter.example.com` pela URL do seu Reporter.

## Passo 1: Fazer upload de uma template

***

Faça upload de um arquivo `.tpl` que define a estrutura e o conteúdo do seu relatório. O conteúdo do arquivo deve corresponder ao formato de saída desejado (HTML, XML, CSV, TXT), mas o arquivo em si deve ter extensão `.tpl`.

<Tip>
  Referência da API: [Upload de template](/pt/reference/reporter/upload-template)
</Tip>

```bash cURL theme={null}
curl -X POST "https://reporter.example.com/v1/templates" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769" \
 -F "template=@account_summary.tpl" \
 -F "outputFormat=PDF" \
 -F "description=Relatório de resumo diário de contas"
```

```json theme={null}
{
  "id": "0196b270-a315-7137-9408-3f16af2685e1",
  "outputFormat": "PDF",
  "description": "Relatório de resumo diário de contas",
  "fileName": "0196b270-a315-7137-9408-3f16af2685e1.tpl",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:00:00Z"
}
```

Guarde o `id` da template. Você o usará para gerar relatórios.

### Formatos de saída suportados

| Formato | Caso de uso                                          |
| ------- | ---------------------------------------------------- |
| `CSV`   | Exportações de dados e integração com planilhas      |
| `XML`   | Dados estruturados e envios regulatórios             |
| `HTML`  | Relatórios visualizáveis no navegador                |
| `PDF`   | Documentos prontos para impressão e compartilhamento |
| `TXT`   | Texto simples e integração com sistemas legados      |

## Passo 2: Verificar a template

***

Liste suas templates para confirmar que o upload foi bem-sucedido.

<Tip>
  Referência da API: [Listar templates](/pt/reference/reporter/list-templates)
</Tip>

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/templates" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769"
```

## Passo 3: Gerar um relatório

***

Envie uma requisição de geração de relatório com o ID da template e filtros opcionais para restringir os dados.

<Tip>
  Referência da API: [Criar relatório](/pt/reference/reporter/create-report)
</Tip>

```bash cURL theme={null}
curl -X POST "https://reporter.example.com/v1/reports" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769" \
 -H "Content-Type: application/json" \
 -d '{
   "templateId": "0196b270-a315-7137-9408-3f16af2685e1",
   "filters": {
     "midaz_onboarding": {
       "account": {
         "created_at": {
           "between": ["2026-03-01", "2026-03-05"]
         }
       }
     }
   }
 }'
```

```json theme={null}
{
  "id": "0196c5c0-5044-724f-95f3-4b32076e7ad7",
  "templateId": "0196b270-a315-7137-9408-3f16af2685e1",
  "filters": {
    "midaz_onboarding": {
      "account": {
        "created_at": {
          "between": ["2026-03-01", "2026-03-05"]
        }
      }
    }
  },
  "status": "Processing",
  "completedAt": null,
  "createdAt": "2026-03-05T10:05:00Z",
  "updatedAt": "2026-03-05T10:05:00Z",
  "deletedAt": null
}
```

Guarde o `id` do relatório para os próximos passos.

### Estrutura de filtros

Os filtros seguem o caminho: **fonte de dados > tabela > campo > operador > valores**.

| Operador     | Descrição                    | Exemplo                                       |
| ------------ | ---------------------------- | --------------------------------------------- |
| `eq`         | Igual a                      | `{ "eq": ["active"] }`                        |
| `gt` / `gte` | Maior que / maior ou igual   | `{ "gte": ["2026-01-01"] }`                   |
| `lt` / `lte` | Menor que / menor ou igual   | `{ "lt": [1000] }`                            |
| `between`    | Valor dentro de um intervalo | `{ "between": ["2026-03-01", "2026-03-31"] }` |
| `in` / `nin` | Valor em / não em uma lista  | `{ "in": ["active", "pending"] }`             |

<Info>
  Os filtros são opcionais. Omita-os para gerar um relatório com todos os dados disponíveis.
</Info>

## Passo 4: Verificar status do relatório

***

A geração de relatórios é assíncrona. Consulte o endpoint de status até que o relatório esteja pronto.

<Tip>
  Referência da API: [Verificar status do relatório](/pt/reference/reporter/check-report-status)
</Tip>

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769"
```

| Status              | Significado                                                                             |
| ------------------- | --------------------------------------------------------------------------------------- |
| `Processing`        | O Reporter está consultando dados e renderizando a template                             |
| `PendingExtraction` | O relatório está aguardando a conclusão da extração de dados antes de iniciar a geração |
| `Finished`          | O relatório está pronto para download                                                   |
| `Error`             | Ocorreu um erro durante a geração                                                       |

Aguarde o status `Finished` antes de prosseguir para o download.

## Passo 5: Baixar o relatório

***

Quando o relatório estiver finalizado, baixe o arquivo gerado.

<Tip>
  Referência da API: [Baixar relatório](/pt/reference/reporter/download-report)
</Tip>

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7/download" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769" \
 -o account_summary.pdf
```

O arquivo é retornado com cabeçalhos `Content-Disposition` indicando o nome do arquivo e formato.

## Passo 6: Explorar fontes de dados

***

Para entender quais dados estão disponíveis para suas templates, liste as fontes de dados configuradas e seus esquemas.

<Tip>
  Referência da API: [Listar fontes de dados](/pt/reference/reporter/list-data-sources) | [Obter fonte de dados](/pt/reference/reporter/retrieve-data-source)
</Tip>

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/data-sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Organization-Id: 019c96a0-0a98-7287-9a31-786e0809c769"
```

Cada fonte de dados inclui tabelas e campos disponíveis que você pode referenciar nas suas templates usando a sintaxe `{{ datasource.table.field }}`.

## Próximos passos

***

<CardGroup cols={2}>
  <Card title="O que é o Reporter?" icon="circle-info" href="/pt/reporter/what-is-reporter">
    Visão completa da sintaxe de templates, tags e filtros.
  </Card>

  <Card title="Formatos de templates" icon="file-code" href="/pt/reporter/template-examples">
    Exemplos práticos para templates HTML, XML e TXT.
  </Card>

  <Card title="Usando o Reporter" icon="rocket" href="/pt/reporter/using-reporter">
    Guia detalhado sobre templates, armazenamento e configuração de fontes de dados.
  </Card>

  <Card title="Tratamento de erros" icon="triangle-exclamation" href="/pt/reference/reporter/reporter-error-list">
    Lista completa de códigos de erro e como resolvê-los.
  </Card>
</CardGroup>