Como construir um conector de API customizado em minutos, com um agente de IA e sem escrever Python

Toda equipe de dados tem aquela API

Toda equipe de dados tem pelo menos uma API que nenhuma ferramenta de ingestão cobre. Pode ser um sistema interno, um SaaS de nicho do seu setor ou o fornecedor que só a sua empresa usa.

O Custom Connector da Erathos resolve exatamente esse caso. Você descreve a API em alguns arquivos YAML, aponta a Erathos para o repositório no GitHub, e o conector aparece no catálogo como qualquer outro. Agora, com a skill de agente que incluímos no template, nem os YAMLs você precisa escrever à mão.

Neste post, mostramos o fluxo completo com um caso real: construímos um conector para a API da Salvy, do zero até os dados no BigQuery.

O problema: o script que ninguém quer manter

Quando não existe conector pronto, a saída costuma ser um script Python rodando num cron, numa Cloud Function ou num DAG do Airflow. Funciona no primeiro dia. O custo aparece depois:

• Paginação, retries e rate limit reimplementados em cada script, cada um de um jeito.
• Falhas silenciosas. A API devolve 404 ou muda um campo, o job "passa" e a tabela fica vazia ou incompleta sem ninguém perceber.
• Zero observabilidade. Sem histórico de execuções, sem alerta, sem saber quantas linhas entraram em cada sync.
• Conhecimento concentrado. Só quem escreveu entende o código. Quando essa pessoa sai, o pipeline vira caixa-preta.

O resultado é que a API de nicho, justamente a que mais diferencia o seu negócio, vira o elo mais frágil do stack de dados.

O que é o Custom Connector

O Custom Connector é um conector definido por código declarativo que vive no seu repositório do GitHub. A Erathos observa esse repositório e reconstrói a imagem do conector a cada push.

O projeto parte do template erathos-data/custom-api-connector. Nele, cada endpoint da API é um arquivo YAML, e um _default.yml guarda o que é comum a todos: URL base, autenticação, códigos HTTP e o endpoint de validação. O template já cobre:

• Autenticação: bearer token e OAuth2, entre outros.
• Paginação: por página, offset, token, tempo e GraphQL, com um exemplo de cada no repo.
• Endpoints dependentes: endpoints pai e filho, como /contas/{id}/mensagens.
• Mapeamento de campos, placeholders de variáveis e custom fields.
• Um validador (validate_connector.py) que checa o projeto antes do deploy.

Ninguém escreve Python. E, depois que o primeiro build passa, o conector aparece no catálogo da Erathos com o selo Custom e funciona como qualquer conector nativo: mesma configuração de jobs, mesmos tipos de sync, mesmo monitoramento.

Como o conector é código em Git, ele herda o que o time de dados já usa: revisão por pull request, histórico de mudanças e rollback por commit.

A skill: descreva a API, o agente escreve o conector

A novidade é que o template já vem com uma skill de agente em .claude/skills/custom-api-connector. Ela ensina um agente de código, como o Claude Code, a construir conectores no padrão da Erathos.

A ideia surgiu num teste antes do lançamento. Quem testou o conector via GitHub sugeriu colocar na documentação um prompt pronto para jogar no Claude. Fomos um passo além e empacotamos esse conhecimento como skill.

Na prática, você abre o repositório no agente e pede em linguagem natural, por exemplo: "conecte a API da Acme à Erathos, sincronizando pedidos e clientes de forma incremental". A partir daí, o agente:

1. Lê a documentação ou a spec OpenAPI da API.
2. Pergunta o que não está claro na documentação.
3. Faz chamadas reais à API, quando há credencial, para confirmar o formato das respostas.
4. Gera os YAMLs: _default.yml e um arquivo por endpoint.
5. Roda o validador.
6. Documenta onde cada credencial deve ser configurada.

O ponto importante: a skill não esconde as decisões. Ela explica cada escolha que não é óbvia no YAML e marca o que ainda não foi confirmado contra a API real.

Passo a passo: um conector para a API da Salvy

Para este exemplo, usamos a API v2 da Salvy, por sugestão do Hudo, CTO da Salvy. O fluxo inteiro, do fork aos dados no BigQuery, cabe em poucos minutos de vídeo.

Passo 1: faça o fork do template

Faça um fork de erathos-data/custom-api-connector para a sua conta ou organização. Se já tiver um repositório, basta copiar a pasta .claude/skills/ para ele.

Passo 2: peça o conector ao agente

Clone o repositório, abra no Claude Code e mande um prompt curto:

crie um custom-api-connector para a API da Salvy:
https://docs.salvy.com.br/api-reference/v2/introduction
usando a skill do repo

O agente leu a documentação, mapeou os endpoints e devolveu este resumo:

Mais interessante que a tabela são as decisões que ele explicou por conta própria:

• Endpoint de validação. A v2 não tem /me, então ele usou /virtual-phone-accounts/area-codes, o GET autenticado mais barato, que devolve 401 com chave inválida.
• 404 não é ignorado globalmente. Só em sms_messages, onde uma linha cancelada entre a chamada do pai e a do filho é esperada. Em listagens, 404 significa caminho errado, e silenciá-lo geraria syncs de zero linhas sem erro.
• includeArchived: "true" em assets. O padrão da API exclui arquivados, o que faria equipamentos sumirem da tabela sem rastro.
• customFields e detections como JSON, porque são estruturas cujo formato muda sem aviso.
• Custo do endpoint filho explicitado: N linhas × M páginas por sync, com o cursor mantendo M próximo de 1 depois da primeira carga.

Ele também conferiu os 41 campos contra a spec OpenAPI oficial e marcou tudo como # UNVERIFIED, porque transcreveu da spec e não de respostas HTTP reais. A recomendação foi rodar um curl com chave de sandbox antes do merge.

Passo 3: commit e pull request

Pedimos para o agente commitar numa branch e abrir o PR. Ele criou a branch salvy-v2-connector com 13 arquivos (4 endpoints novos, _default.yml reescrito, exemplos do template removidos) e uma descrição de PR com as decisões acima. O time revisa como revisaria qualquer código.

Passo 4: conecte o repositório na Erathos

Em Connections → New Connection → Select datasource, clique em Custom connector via GitHub. Na primeira vez, você instala o GitHub App da Erathos e autoriza o repositório (é preciso ser admin da conta ou organização).

Depois, informe o repositório no formato owner/repo, o nome da fonte como vai aparecer no catálogo e, se quiser, um ícone. O primeiro build pode levar alguns minutos. Os repositórios observados ficam listados em Settings → Workspace → Repositories.

Passo 5: crie a conexão e configure os jobs

A Salvy aparece no catálogo com o selo Custom. Daqui em diante, é o fluxo de qualquer conector:

1. Crie a conexão e informe a API key.
2. Escolha o schema de destino (no vídeo, salvy).
3. Em Manage Jobs, ative os endpoints e defina frequência, tipo de sync e horário.
4. Rode o primeiro sync.

No BigQuery, o dataset salvy_raw aparece com as tabelas area_codes, assets e virtual_phone_accounts, já com as colunas de controle da Erathos: _erathos_execution_id, _erathos_metadata e _erathos_synced_at.

Depois do deploy: controle e observabilidade de conector nativo

O ganho real não é só construir rápido. É que o conector custom roda na mesma plataforma dos nativos, com o mesmo nível de controle:

• Jobs por endpoint. Cada endpoint vira um job com frequência, tipo de sync (full refresh ou incremental) e horário próprios. Endpoints filhos aparecem com trigger do tipo Parent Job.
• Histórico de execuções. Na tela de Jobs, cada execução recente aparece como sucesso ou falha, lado a lado com os conectores de GitHub, bancos e SaaS.
• Rastreabilidade linha a linha. As colunas _erathos_execution_id e _erathos_synced_at dizem de qual execução e de quando veio cada registro.
• Mudanças versionadas. A API mudou? Você (ou o agente) ajusta o YAML, abre um PR, faz o merge, e a Erathos reconstrói o conector sozinha.

Na prática, aquela API de nicho deixa de ser um script isolado e passa a ter a mesma observabilidade do resto do stack.

Quando usar (e quando não usar)

Use o Custom Connector quando:

• A fonte é uma API REST ou GraphQL sem conector pronto no catálogo.
• É uma API interna da sua empresa.
• Você quer versionar e revisar a lógica de ingestão como código.

Prefira outro caminho quando:

• Já existe conector nativo para a fonte. Veja o catálogo.
• A fonte não é uma API HTTP, como um banco de dados ou arquivos.
• Você não quer manter um repositório. Nesse caso, use o Request a connector na tela de seleção de fontes.

Uma boa prática com a skill: trate o que o agente marca como # UNVERIFIED como pendência real. Antes do merge, rode uma chamada com credencial de sandbox para confirmar o formato das respostas.

Comece agora

Com o Custom Connector, a API que nenhuma ferramenta cobre passa a ter o mesmo controle e a mesma observabilidade dos conectores nativos. Com a skill, o caminho entre "preciso desses dados" e "a tabela está no warehouse" virou uma conversa com o agente e um pull request.

• Assista ao vídeo com o fluxo completo da Salvy: [inserir link do vídeo]
• Leia a documentação: Custom Connectors
• Faça o fork do template: erathos-data/custom-api-connector
• Crie sua conta grátis na Erathos, sem cartão de crédito.