> ## 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.

# Integração e incorporação do Reporter

> Integre o Reporter a partir do seu próprio software: a superfície REST que executa cada operação, a URL base e o modelo de autenticação, uma primeira chamada e o padrão para executar o Reporter atrás de um serviço que você já opera.

A API REST do Reporter é a superfície completa. Templates, relatórios, fontes de dados, prazos, instituições, remessa regulatória, o construtor de templates e métricas são todos chamadas HTTP. Nada existe apenas dentro de uma biblioteca cliente, e nada existe apenas dentro do Console.

## Autenticando

***

Um único esquema protege todas as operações: um bearer token no cabeçalho `Authorization`.

```
Authorization: Bearer <token>
```

O Access Manager autoriza cada chamada com base no recurso atrás do caminho e na ação. O recurso é um entre templates, relatórios, fontes de dados, prazos, instituições, regulatório, aprovação regulatória, métricas ou streaming, e a ação é o verbo HTTP. Um token com acesso de leitura a relatórios pode listá-los e baixá-los, e recebe um `403` ao tentar criar. Falhas respondem em `application/problem+json`, então faça o parse do documento de problema em vez de olhar apenas a linha de status.

O token também carrega o escopo de isolamento da chamada. O Reporter o resolve a partir da própria credencial, então nenhuma operação recebe um cabeçalho de escopo do seu cliente, e nenhum cabeçalho amplia o que um token já permite.

## URL base

***

O caminho base é `/v1`, sem nenhum segmento de produto antes dele. Todo caminho nesta página é anexado a isso:

```
https://reporter.example.com/v1
```

Três regras de content-type decorrem da própria superfície. O upload e a atualização de template são `multipart/form-data`, porque um template é um arquivo `.tpl`. A criação de relatório é `application/json`. Um download transmite os bytes renderizados com o `Content-Type` do formato de saída e um nome de arquivo `Content-Disposition`.

A maioria das operações de listagem aceita `limit` e `page`, com padrão 10 e 1. A listagem de relatórios aceita `limit` e um `cursor` da página anterior em vez disso. O maior valor de página é `MAX_PAGINATION_LIMIT`, que cada deploy define e que tem padrão 100. Um `limit` acima desse limite é rejeitado, não reduzido.

## Sua primeira chamada

***

**1. Confirme o token e a URL base**

```bash theme={null}
curl -s "https://reporter.example.com/v1/templates" \
  -H "Authorization: Bearer $TOKEN"
```

Um `200` com uma lista de templates confirma os dois. Um `401` indica problema no token. Um `404` indica problema na URL base.

**2. Solicite um relatório**

```bash theme={null}
curl -s -X POST "https://reporter.example.com/v1/reports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency: daily-balance-2026-07-28" \
  -d '{
    "templateId": "0196b270-a315-7137-9408-3f16af2685e1",
    "filters": {
      "midaz_onboarding": {
        "account": { "status": { "eq": ["ACTIVE"] } }
      }
    }
  }'
```

A resposta é `201` com o relatório em `Processing`. A geração é executada de forma assíncrona.

**3. Espere um estado que permita o download e então baixe**

```bash theme={null}
curl -s "https://reporter.example.com/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $TOKEN"

curl -s "https://reporter.example.com/v1/reports/$REPORT_ID/download" \
  -H "Authorization: Bearer $TOKEN" -o report.pdf
```

O download entrega um relatório `Finished` ou `Final`, e um `Draft` sem campo obrigatório em branco. Veja [Como funciona a geração de relatórios](https://docs.lerian.studio/pt/products/reporter/how-report-generation-works.md).

Envie `X-Idempotency` em toda requisição de relatório, e no upload de template pelo mesmo motivo. Repita uma requisição que ainda está em andamento e você recebe um erro em vez de um segundo relatório. Repita uma que já terminou e o Reporter reproduz o relatório original, marcando a resposta com `X-Idempotency-Replayed: true`.

Um relatório é criado uma vez e mantido: create, get, list e download são suas quatro operações. Por quanto tempo um arquivo renderizado permanece é uma política de ciclo de vida do bucket de armazenamento, não uma chamada de API.

## Gerenciando fontes de dados

***

A API gerencia o registro persistido de fontes de dados. Use-a para listar ou criar conexões, obter ou atualizar parcialmente uma por `dataSourceId`, inspecionar seu schema em tempo real, testá-la ou fazer soft-delete dela:

```bash theme={null}
curl -s "https://reporter.example.com/v1/data-sources" \
  -H "Authorization: Bearer $TOKEN"
```

Cada entrada carrega o `configName` estável que os templates referenciam. As respostas nunca contêm senhas. Busque uma pelo identificador com `/v1/data-sources/{dataSourceId}` e inspecione suas tabelas ou coleções em tempo real com `/v1/data-sources/{dataSourceId}/schema`.

## Executando o Reporter atrás do seu próprio serviço

***

O Reporter é um serviço que você faz deploy, não uma biblioteca que você vincula. Para colocá-lo atrás de uma aplicação que seus clientes já usam, mantenha as credenciais do seu lado e chame o Reporter de servidor para servidor. Quatro regras mantêm essa fronteira limpa.

**Nunca entregue um token do Reporter a um navegador.** Seu serviço autentica seu usuário e decide se esse usuário pode executar este relatório. Depois ele faz a chamada com o próprio token.

**Responda imediatamente com um identificador.** A criação do relatório retorna em `Processing`. Devolva esse identificador a quem chamou e deixe seu próprio endpoint de status expor o progresso.

**Saiba da conclusão apenas uma vez.** Faça poll de `GET /v1/reports/{id}` em um intervalo moderado, ou se inscreva nos eventos de relatório do Reporter e pare de fazer poll. Veja [Eventos do Reporter](https://docs.lerian.studio/pt/products/reporter/reporter-events.md).

**Faça proxy do download.** O endpoint de download transmite bytes a um chamador autenticado, então seu serviço busca esses bytes e os reoferece sob sua própria autenticação.

> [!NOTE]
>
> Um relatório `Partial` significa que algumas seções de dados falharam enquanto outras tiveram sucesso, e os metadados dele nomeiam as seções com falha. Trate isso como um sinal sobre uma fonte de dados ou um filtro, e decida no seu próprio serviço o que seus usuários devem ver.

## Próximos passos

***

> [card] [API REST do Reporter](https://docs.lerian.studio/pt/products/reporter/reporter-rest-api.md)
>
> Todas as operações, agrupadas pela tarefa que executam.

> [card] [Eventos do Reporter](https://docs.lerian.studio/pt/products/reporter/reporter-events.md)
>
> O contrato de eventos e como se inscrever em vez de fazer poll.

> [card] [Início rápido da API](https://docs.lerian.studio/pt/reference/products/reporter/reporter-developer-quick-start.md)
>
> Envie um template e gere um relatório com cURL.

> [card] [Lista de erros](https://docs.lerian.studio/pt/reference/products/reporter/reporter-error-list.md)
>
> Os códigos de erro do Reporter e o que os resolve.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.