Voltar para a documentaçãoConectores

Conectores personalizados

Adicione um conector personalizado com uma chave de API ou credencial OAuth.

Última atualização em 10 de julho de 2026 · 6 min read

O catálogo cobre mais de 100 serviços, mas toda equipe tem algumas ferramentas internas ou produtos SaaS regionais que não estão nele. Os conectores personalizados resolvem isso.

Você registra uma credencial — uma chave de API ou credenciais OAuth — e diz ao Zero como chamar o serviço. A partir daí, o Zero trata o seu conector personalizado de forma idêntica a um nativo: mesmo log de auditoria, mesmo proxy de acesso intermediado, mesmos controles de ações sensíveis.

Dois tipos

Escolha o tipo que corresponde ao seu serviço:

  • Chave de API — funciona para qualquer serviço que se autentica com um token estático em um cabeçalho. O caminho mais simples e rápido: cole a chave, nomeie o conector, aponte o Zero para a URL base. A maioria das APIs internas e muitas ferramentas SaaS usam isso.
  • OAuth 2.0 — para serviços que emitem tokens por usuário via OAuth. Você fornece um client ID e um secret, configura os escopos que quer que o Zero possa solicitar, e o Zero executa o fluxo OAuth por usuário quando necessário.

Se você não tem certeza de qual usar, consulte a documentação da API do serviço upstream. A expressão "API key" (ou "personal access token") geralmente indica o tipo 1; "OAuth" (ou "client credentials") geralmente indica o tipo 2.

Configurando um conector com chave de API

  1. Abra a página Connectors no seu espaço de trabalho.
  2. Clique em Add custom connector → API key.
  3. Preencha:
    • Name. Algo que o Zero possa reconhecer ao ler prompts, por exemplo, internal-billing-api ou acme-crm.
    • Base URL. A raiz da API: https://api.internal.acme.com.
    • Auth header. Normalmente Authorization: Bearer YOUR_TOKEN ou X-API-Key: YOUR_TOKEN. Corresponda ao que o serviço espera.
    • API key. Cole a credencial. Armazenada criptografada; nunca visível após salvar.
    • Allowed paths (opcional). Restrinja o Zero a endpoints específicos, como /v1/invoices/*. Reduz o raio de impacto.
  4. Clique em Save e Test connection. O Zero faz um ping na URL base com um GET / (ou um caminho que você especificar) e reporta a resposta.

Configurando um conector OAuth 2.0

Um pouco mais de trabalho, mas vale a pena para serviços em que a autorização por usuário importa:

  1. Registre um aplicativo OAuth com o serviço upstream. Você receberá um client ID e um client secret. Defina a redirect URI como a que a VM0 exibe no formulário de adicionar conector.
  2. Na VM0: Add custom connector → OAuth 2.0.
  3. Preencha:
    • Name e Base URL, como acima
    • Authorization URL e Token URL da documentação OAuth do serviço upstream
    • Client ID e Client secret
    • Scopes. A lista de escopos que o Zero pode solicitar. Use o mínimo que cobre seus fluxos de trabalho.
  4. Salve. A primeira sessão que precisar desse conector dispara o fluxo OAuth por usuário.

Ensinando o Zero a usar um conector personalizado

Duas formas. Escolha a que se encaixa no seu fluxo de trabalho.

Descreva inline quando pedir ao Zero para fazer algo:

"Use o conector internal-billing-api para buscar a fatura #4422. Depois envie o PDF por e-mail para ops@acme.com."

O Zero carrega a especificação do conector e descobre qual endpoint chamar. Isso funciona porque os conectores vêm com metadados no estilo OpenAPI (descobertos automaticamente para muitos serviços, opcionalmente fornecidos manualmente).

Escreva uma skill que faça referência ao conector pelo nome. O corpo da skill descreve o procedimento; o Zero carrega a skill automaticamente quando a descrição corresponde a uma solicitação recebida. Para fluxos de trabalho repetidos, isso é mais limpo do que redescrever inline toda vez.

Uma skill chamada pull-invoice com a descrição "buscar uma fatura do internal-billing-api e enviar o PDF por e-mail" — depois de escrita, o Zero a invoca sempre que alguém pede uma fatura.

Especificações OpenAPI e esquemas inline

O Zero funciona melhor com um conector personalizado quando conhece os endpoints, métodos e parâmetros disponíveis. Há três formas de fornecer isso:

  • Descoberta automática a partir do /openapi.json ou /swagger.json do serviço, se ele expuser um. Basta apontar o Zero para a URL.
  • Enviar uma especificação. Cole ou envie um OpenAPI 3 em YAML/JSON. O Zero o analisa e oferece metadados em estilo tooltip ao construir chamadas.
  • Descrições inline. Para ferramentas internas sem especificações, você pode escrever uma breve descrição em markdown no corpo do conector — endpoints, métodos, payloads de exemplo. Rudimentar, mas funcional.

Sem uma especificação, o Zero ainda funciona — ele apenas precisa adivinhar mais sobre os formatos dos parâmetros. Para conectores personalizados usados com frequência, uma especificação se paga rapidamente.

Compartilhamento entre espaços de trabalho

Conectores personalizados têm escopo por espaço de trabalho por padrão. Duas equipes na mesma organização podem cada uma manter seu próprio conector personalizado para a mesma API interna. Para organizações que querem uma configuração canônica:

  • Conectores no nível da organização (enterprise). Disponíveis em planos enterprise. Configure uma vez no nível da organização; aparece em todos os espaços de trabalho sob essa organização. Recomendado para APIs internas que todos usam.
  • Pacote de conector. Para organizações muito grandes, a equipe de plataforma interna pode publicar um conector personalizado como um pacote versionado; os espaços de trabalho o instalam e recebem atualizações automaticamente.

Segurança e limites de taxa

  • Credenciais. Criptografadas em repouso com chaves por espaço de trabalho. Nunca visíveis após salvar; apenas reinseríveis.
  • Auditoria por chamada. Cada requisição por meio de um conector personalizado aparece no log da sessão com método, URL, código de status e tempo.
  • Limites de taxa. Aplicados pelo serviço upstream. O Zero trata respostas 429 com backoff exponencial até um limite configurado por espaço de trabalho.
  • Caminhos em lista de permissões. Opcional: restrinja o Zero a padrões de URL específicos. Reduz o raio de impacto se a chave de um conector for excessivamente privilegiada.
  • Somente leitura por padrão. Um novo conector personalizado é marcado como somente leitura. Conceder acesso de escrita exige configuração explícita por espaço de trabalho.

Armadilhas comuns

  • Chaves de API amplas demais. Se o seu serviço permitir, gere uma chave com escopo para o Zero em vez de reutilizar a sua chave de administrador pessoal. Mais fácil de rotacionar e auditar.
  • Esquemas ausentes. Sem uma especificação OpenAPI ou descrição inline, o Zero adivinha os formatos dos parâmetros. Isso funciona para casos simples e falha para objetos aninhados. Forneça uma especificação quando puder.
  • URLs base não testadas. Sempre clique em Test connection após a configuração. Um 401 ou 404 nesta etapa é muito melhor do que um 401 em uma sessão crítica.
  • Esquecer de rotacionar. Configure um lembrete no calendário para rotacionar chaves trimestralmente. A rotação de chave de conector é um clique na VM0; a rotação upstream é o que leva a maior parte do tempo.

O que vem a seguir

  • Veja Skills para capturar fluxos de trabalho repetidos de conectores personalizados.
  • Veja Permissions para saber como as credenciais de conectores personalizados são tratadas.
  • Veja o Catálogo antes de criar um personalizado — seu serviço pode já ser suportado.