> ## 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. # API REST do Fetcher > Oriente-se na API do Manager do Fetcher: autenticação bearer, escopo de produto, paginação, filtragem e o formato de erro RFC 9457 que as 12 operações compartilham. O **Manager** serve a API HTTP do Fetcher. Ela carrega 12 operações em duas áreas: * **Jobs de extração** em `/v1/fetcher` — criar um job, ler um job. * **Conexões** em `/v1/management/connections` — o ciclo de vida da conexão, leituras de esquema, testes de conexão e as duas operações de atribuição de produto. Todas as 12 operações são renderizadas sob a âncora **Fetcher** na [Referência de API](/pt/reference/introduction). Esta página cobre o que essas operações compartilham. Ela não repete os formatos de requisição e resposta. Os documentos OpenAPI deste portal são fontes de renderização para as páginas de referência. Eles não são contratos de cliente e não servem de base para a geração de SDKs. ## Autenticação *** O Fetcher aceita um token JWT bearer: ```http theme={null} Authorization: Bearer ``` A autenticação é uma escolha de implantação. `PLUGIN_AUTH_ENABLED` liga o middleware de autenticação, e `PLUGIN_AUTH_ADDRESS` o aponta para o serviço de identidade. O Manager recusa iniciar quando você habilita a autenticação e deixa o endereço vazio. O modo multi-tenant também exige autenticação efetiva — o roteador recusa montar um middleware de tenant sem ela. Veja [Configuração](/pt/fetcher/fetcher-configuration). Cada uma das 12 operações declara `401` e `403`. O Fetcher autoriza cada requisição contra a aplicação `fetcher`, um recurso (`connections` ou `fetcher`) e uma ação que corresponde ao método HTTP. Cinco rotas ficam fora da autenticação para que as sondas continuem funcionando: `/health`, `/readyz`, `/readyz/tenant/{id}`, `/metrics` e `/version`. ## Escopo de produto *** As operações de conexão carregam um cabeçalho `X-Product-Name`. Ele nomeia o produto dono da conexão. * **Criar conexão exige o cabeçalho.** O Fetcher rejeita um valor ausente, vazio ou composto apenas de espaços. * **Listar conexões trata o cabeçalho como opcional.** Com ele, você vê as conexões de um produto. Sem ele, você vê todas as conexões no escopo. * O Fetcher converte o valor para minúsculas. Ele aceita letras, dígitos, sublinhados e hifens, até 100 caracteres. Jobs de extração não usam esse cabeçalho. Um job nomeia o produto dono em `metadata.source`, campo que o payload de criação exige. ## Jobs assíncronos *** `POST /v1/fetcher` responde `202 Accepted` e retorna um identificador de job com status `pending`. O Worker executa a extração depois da resposta. O Fetcher deduplica requisições de job por um hash da requisição, dentro de uma **janela de 5 minutos**. Uma duplicata dentro dessa janela responde `200 OK` e retorna o job existente, em vez de enfileirar um segundo. Um job que já falhou não suprime uma nova tentativa — você pode reenviá-lo. Para acompanhar um job, consulte `GET /v1/fetcher/{id}` periodicamente, ou assine os eventos terminais descritos em [Eventos de job](/pt/fetcher/fetcher-job-events). ## Paginação *** As duas operações de listagem — conexões e conexões sem produto — usam paginação por deslocamento, com os mesmos parâmetros de consulta. | Parâmetro | Padrão | Regras | | ----------- | ------ | ------------------------------------------------------------------------------------------- | | `page` | `1` | Número da página. Deve ser 1 ou maior. | | `limit` | `10` | Itens por página. Deve ser 1 ou maior, e no máximo `MAX_PAGINATION_LIMIT` (100 por padrão). | | `sortOrder` | `desc` | `asc` ou `desc`. O Fetcher sempre ordena pela data de criação. | | `startDate` | — | Limite inferior inclusivo sobre a data de criação, no formato `YYYY-MM-DD`. | | `endDate` | — | Limite superior inclusivo sobre a data de criação, no formato `YYYY-MM-DD`. | A resposta de uma página carrega `items`, `page`, `limit` e `total`. ```json theme={null} { "items": [], "page": 1, "limit": 10, "total": 42 } ``` Uma requisição de listagem sempre aplica uma janela de data de criação. Se você não enviar `startDate` nem `endDate`, o Fetcher aplica o último mês até amanhã. Conexões mais antigas ficam fora dessa janela. Defina as duas datas quando quiser uma visão mais ampla. `MAX_PAGINATION_MONTH_DATE_RANGE` limita a largura dessa janela em um mês por padrão. Se você pedir um intervalo maior, o Fetcher avança `startDate` para caber no limite. Ele não responde com erro. Fontes de dados internas — aquelas que um operador configura pelas variáveis de ambiente `DATASOURCE_{NAME}_*` — aparecem apenas na página 1, à frente das conexões armazenadas, e contam para o `total`. ## Filtragem *** A listagem de conexões aceita dois filtros além da janela de datas. * **`type`** — um entre `POSTGRESQL`, `MYSQL`, `ORACLE`, `SQL_SERVER` ou `MONGODB`. O Fetcher converte o valor para maiúsculas. * **`metadata.=`** — correspondência exata com uma entrada de metadados que você armazenou junto com a conexão. Por exemplo, `metadata.region=br`. A listagem de conexões sem produto restringe apenas pela janela de datas. Ela responde a uma única pergunta — quais conexões ainda não têm produto — então não aceita filtro de tipo nem de metadados. O Fetcher ignora um parâmetro de consulta desconhecido em vez de falhar a requisição. Três casos ainda falham com `FET-0405`: * Uma chave que começa com `$`, o que bloqueia injeção de operadores de consulta. * Uma chave que começa com `_`, o que bloqueia campos internos. * Uma chave com mais de 64 caracteres, ou um valor com mais de 256 caracteres. ## Erros *** Todo erro responde `application/problem+json` e segue a [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). ```json theme={null} { "type": "about:blank", "title": "Invalid payload", "status": 400, "detail": "empty request body", "code": "FET-0001", "errors": [ { "location": "body.configName", "message": "is required" } ] } ``` | Campo | O que carrega | | ---------- | ---------------------------------------------------------------------------------------------- | | `type` | Referência URI para a documentação do problema. O padrão é `about:blank`. | | `title` | Resumo curto do tipo de problema. Estável entre ocorrências. | | `status` | O código de status HTTP. | | `detail` | Explicação específica desta ocorrência. | | `instance` | Referência URI para esta ocorrência específica. | | `code` | Código de erro de domínio estável, no formato `FET-NNNN`. | | `errors` | Detalhes opcionais por campo, cada um com `location`, `message` e o `value` que causou o erro. | Faça a correspondência por `code`, não por `title` ou `detail`. Os códigos se agrupam por faixa: | Faixa | Significado | Exemplos | | ---------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `FET-000x` | Resultados gerais | `FET-0001` requisição inválida, `FET-0002` erro interno, `FET-0004` conflito, `FET-0005` não encontrado | | `FET-04xx` | Problemas na requisição | `FET-0403` cabeçalho inválido, `FET-0405` parâmetro de consulta inválido, `FET-0406` limite de paginação excedido, `FET-0414` host proibido | | `FET-10xx` | Regras de negócio | `FET-1002` conflito de entidade, `FET-1021` job em andamento, `FET-1040` conexão indisponível | | `FET-106x` | Validação de esquema | `FET-1060` validação falhou, `FET-1062` objeto não encontrado | O Fetcher oculta falhas de nível de driver na sua fronteira. Ele descarta o erro bruto do banco, de modo que uma string de conexão, uma credencial ou um detalhe interno do driver nunca chega a quem chamou. ## Ler a especificação a partir de um Manager em execução *** `SWAGGER_ENABLED=true` monta uma referência Scalar em `/swagger/docs` e o documento OpenAPI 3.1 em `/swagger/openapi.json` e `/swagger/openapi.yaml`. Mantenha essa opção desligada em produção. ## Próximos passos *** As 12 operações, com os formatos completos de requisição e resposta. Reaja a `job.completed` e `job.failed` em vez de consultar periodicamente. Conexões, descoberta de esquema, jobs de extração, filtros e resultados. As variáveis de ambiente por trás da autenticação, dos limites de paginação e da superfície da API.