API REST do Fetcher

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. 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:

Authorization: Bearer <token>

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

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.

{
  "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.<key>=<value> — 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.

{
  "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

Referência de API

As 12 operações, com os formatos completos de requisição e resposta.

Eventos de job

Reaja a job.completed e job.failed em vez de consultar periodicamente.

Conceitos centrais

Conexões, descoberta de esquema, jobs de extração, filtros e resultados.

Configuração

As variáveis de ambiente por trás da autenticação, dos limites de paginação e da superfície da API.

Visão geral

Primeiros passos

Conceitos

Motor

Integração

Operações

API REST do Fetcher

Autenticação

Escopo de produto

Jobs assíncronos

Paginação

Filtragem

Erros

Ler a especificação a partir de um Manager em execução

Próximos passos

Referência de API

Eventos de job

Conceitos centrais

Configuração

​Autenticação

​Escopo de produto

​Jobs assíncronos

​Paginação

​Filtragem

​Erros

​Ler a especificação a partir de um Manager em execução

​Próximos passos

Referência de API

Eventos de job

Conceitos centrais

Configuração

Autenticação

Escopo de produto

Jobs assíncronos

Paginação

Filtragem

Erros

Ler a especificação a partir de um Manager em execução

Próximos passos