> ## 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 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, o SDK em Go 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, 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 ``` 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 *** ```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. ```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. ```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 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: ```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`. ## O SDK em Go *** [`lerian-sdk-golang`](https://github.com/LerianStudio/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:///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. ```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 } } ``` `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](/pt/products/reporter/reporter-events). **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 *** Todas as operações, agrupadas pela tarefa que realizam. O contrato de eventos e como assinar em vez de fazer poll. Envie um template e gere um relatório com cURL. Os códigos de erro do Reporter e o que os resolve.