SDK e incorporação do Reporter

A API REST do Reporter é a superfície completa. Templates, relatórios, fontes de dados, prazos, 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, 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. Operações de listagem aceitam limit e page, com padrão 10 e 1. 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

Confirme o token e a URL base

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.

Solicite um relatório

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.

Espere um estado terminal e então baixe

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 exige Finished.

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. Derive a chave a partir do seu próprio identificador de requisição e uma nova tentativa não custa nada. 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:

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.

O SDK em Go

lerian-sdk-golang traz um pacote reporter junto com os outros produtos Lerian. Ele é uma conveniência sobre as chamadas acima para trabalhar com templates e relatórios. Ele obtém um token OAuth2 client-credentials, renova esse token e devolve resultados tipados e iteradores paginados. Configure-o com a mesma URL base https://<host>/v1 que você usa com cURL. Adicione o client ID, o client secret, a URL de token do seu servidor de autorização e um timeout de requisição.

report, err := client.Reporter.Reports.Get(ctx, reportID)
if err != nil {
    return err
}

if report.Status == "Finished" {
    data, err := client.Reporter.Reports.Download(ctx, reportID)
    if err != nil {
        return err
    }

    if err := os.WriteFile(reportID+"."+report.Format, data, 0o600); err != nil {
        return err
    }
}

Download retorna os bytes renderizados no formato do próprio relatório. Grave-os em disco, como acima, ou transmita-os para quem chamou. O SDK cobre uma parte do produto, não tudo. Ele traz create, get, list e delete de template, e create, get, list e download de relatório. Fontes de dados, atualização de template, prazos, o construtor de templates, métricas e o manifesto de streaming são chamadas REST. Combinar os dois em uma mesma integração é normal: use o pacote onde ele se encaixa e HTTP puro no restante.

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 assine os eventos de relatório do Reporter e pare de fazer poll. Veja Eventos do Reporter. 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.

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

API REST do Reporter

Todas as operações, agrupadas pela tarefa que realizam.

Eventos do Reporter

O contrato de eventos e como assinar em vez de fazer poll.

Início rápido da API

Envie um template e gere um relatório com cURL.

Lista de erros

Os códigos de erro do Reporter e o que os resolve.

Visão geral

Conceitos

Guias

Integração

Console

Operações

SDK e incorporação do Reporter

Autenticando

URL base

Sua primeira chamada

Gerenciando fontes de dados

O SDK em Go

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

Próximos passos

API REST do Reporter

Eventos do Reporter

Início rápido da API

Lista de erros

​Autenticando

​URL base

​Sua primeira chamada

​Gerenciando fontes de dados

​O SDK em Go

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

​Próximos passos

API REST do Reporter

Eventos do Reporter

Início rápido da API

Lista de erros

Autenticando

URL base

Sua primeira chamada

Gerenciando fontes de dados

O SDK em Go

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

Próximos passos