SDK do Reporter e integração embarcada

A API REST do Reporter é a superfície completa. Templates, relatórios, fontes de dados, prazos, o construtor de templates e as métricas são todos chamadas HTTP. Nada existe apenas dentro de uma biblioteca cliente, e nada existe apenas dentro do Console. Comece por ela. Esta página cobre com o que você se autentica, qual é a cara da sua URL base, o que uma primeira chamada devolve, onde o SDK Go poupa seu trabalho e como rodar o Reporter atrás de um serviço com o qual seus próprios usuários já falam.

Autenticação

Um único esquema protege toda operação: um token bearer no cabeçalho Authorization.

Authorization: Bearer <token>

O Access Manager autoriza cada chamada contra o recurso por trás da rota — templates, relatórios, fontes de dados, prazos, métricas ou streaming — e contra a ação, que é o verbo HTTP. Um token com acesso de leitura a relatórios consegue listá-los e baixá-los, e recebe um 403 ao criar. As falhas respondem application/problem+json, então interprete o documento de problema em vez de ficar só na 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 toma um cabeçalho de escopo do seu cliente e nenhum cabeçalho amplia o que um token já permite.

URL base

A rota base é /v1, sem nenhum segmento de produto na frente. Toda rota desta página se acrescenta a ela:

https://reporter.example.com/v1

Da própria superfície saem três regras de content-type. O envio e a atualização de um template são multipart/form-data, porque um template é um arquivo .tpl. A criação de um relatório é application/json. Um download transmite os bytes renderizados com o Content-Type do formato de saída e um nome de arquivo em Content-Disposition. As operações de listagem aceitam limit e page, 10 e 1 por padrão. A maior página é o MAX_PAGINATION_LIMIT, que cada deployment define e cujo padrão é 100. Um limit acima desse teto é recusado, 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 prova os dois. Um 401 aponta para o token; um 404, para a URL base.

Peça 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 corre de forma assíncrona.

Espere um estado terminal e 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 solicitação de relatório, e no envio de um template pelo mesmo motivo. Se você repetir uma solicitação que ainda está em execução, recebe um erro em vez de um segundo relatório. Se repetir uma que já terminou, o Reporter reproduz o relatório original e marca a resposta com X-Idempotency-Replayed: true. Derive a chave do seu próprio identificador de requisição e uma nova tentativa não custa nada. Um relatório é criado uma vez e mantido: criar, obter, listar e baixar são suas quatro operações. Quanto tempo um arquivo renderizado vive é uma política de ciclo de vida sobre o bucket de armazenamento, não uma chamada da API.

Lendo as fontes de dados

Um operador configura as fontes de dados por variáveis de ambiente, então a API sobre elas é somente leitura. Use-a para descobrir o que seus templates podem referenciar:

curl -s "https://reporter.example.com/v1/data-sources" \
  -H "Authorization: Bearer $TOKEN"

Cada entrada carrega o nome de configuração que os templates endereçam, mais suas tabelas e seus campos. Busque uma por identificador com /v1/data-sources/{dataSourceId}.

O SDK Go

O lerian-sdk-golang traz um pacote reporter ao lado dos outros produtos da Lerian. Ele é uma conveniência sobre as chamadas acima para o trabalho com templates e relatórios: obtém um token OAuth2 de client credentials, o renova e devolve resultados tipados e iteradores paginados. Configure-o com a mesma URL base https://<host>/v1 que você usa com o cURL, mais o client ID, o client secret e 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
    }
}

O Download devolve os bytes renderizados no formato do próprio relatório. Escreva-os em disco, como acima, ou transmita-os para quem chamou. O SDK cobre uma parte do produto, não o todo. Ele carrega criar, obter, listar e excluir templates, e criar, obter, listar e baixar relatórios. As fontes de dados, a atualização de template, os prazos, o construtor de templates, as métricas e o manifesto de streaming são chamadas REST. Misturar os dois em uma só integração é normal e esperado: o pacote onde ele encaixa, e HTTP puro em todo o resto.

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

O Reporter é um serviço que você implanta, não uma biblioteca que você linka. Para colocá-lo atrás de uma aplicação que seus clientes já usam, guarde 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, decide se aquele usuário pode executar este relatório e só então faz a chamada com o próprio token. Responda de imediato com um identificador. A criação de um relatório volta em Processing. Devolva esse identificador a quem chamou e deixe seu próprio endpoint de status expor o progresso. Descubra o fim uma vez só. Consulte GET /v1/reports/{id} em um intervalo moderado, ou assine os eventos de relatório do Reporter e pare de consultar. Veja Eventos do Reporter. Faça proxy do download. O endpoint de download transmite bytes para um chamador autenticado, então seu serviço os busca e os serve de novo sob a própria autenticação.

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

Próximos passos

API REST do Reporter

Cada operação, agrupada pelo trabalho que ela faz.

Eventos do Reporter

O contrato de eventos, e como assinar em vez de consultar.

Início rápido da API

Envie um template e gere um relatório com o 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 do Reporter e integração embarcada

Autenticação

URL base

Sua primeira chamada

Lendo as fontes de dados

O SDK Go

Rodando 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

​Autenticação

​URL base

​Sua primeira chamada

​Lendo as fontes de dados

​O SDK Go

​Rodando 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

Autenticação

URL base

Sua primeira chamada

Lendo as fontes de dados

O SDK Go

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

Próximos passos