> ## 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. # SDK do Reporter e integração embarcada > Integre o Reporter a partir do seu próprio software: a superfície REST que carrega toda operação, a URL base e o modelo de autenticação, uma primeira chamada, o SDK Go e o padrão para rodar 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, 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 ``` 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 *** ```bash theme={null} 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. ```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 corre de forma assíncrona. ```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 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: ```bash theme={null} 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`](https://github.com/LerianStudio/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:///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. ```go theme={null} 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](/pt/reporter/reporter-events). **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 *** Cada operação, agrupada pelo trabalho que ela faz. O contrato de eventos, e como assinar em vez de consultar. Envie um template e gere um relatório com o cURL. Os códigos de erro do Reporter e o que os resolve.