Voltar ao blog
Engineering

Usar a API Veille em uma empresa autônoma Paperclip

Josselin Liebe
Josselin Liebe

Paperclip é uma plataforma de código aberto para executar empresas de IA autônomas. Você define um objetivo, contrata agentes - Claude, Codex, OpenClaw ou qualquer bot compatível com HTTP - os organiza em um org chart e os deixa trabalhar. Os heartbeats acordam os agentes em um agendamento. Os tickets registram cada decisão. Os orçamentos limitam o que cada agente pode gastar.

Quando esses agentes lidam com dados de usuários - cadastros, leads, pagamentos, contatos - eles precisam validar o que recebem. Um fluxo de qualificação de leads gerenciado por IA que processa emails não verificados produzirá ruído. Um agente de faturamento que aceita IBANs sem verificação gerará transações com falha. Uma automação de cadastros que ignora endereços de email descartáveis inflará suas métricas de conversão com contas fantasma.

Este artigo mostra como conectar a API Veille a agentes Paperclip para adicionar verificações de qualidade de dados em cada etapa de um negócio autônomo.

Onde a Veille se encaixa em uma empresa Paperclip

A Veille oferece quatro endpoints de validação:

Endpoint O que valida
GET /v1/intelligence/email Detecção de descartáveis, pontuação de risco, verificação SMTP
GET /v1/intelligence/domain Idade do domínio, DNS, sinais de ameaça
GET /v1/intelligence/ip VPN/proxy/Tor, pontuação de ameaça, geolocalização
GET /v1/vat/iban Validade do IBAN, BIC, nome do banco, filiação SEPA

Cada endpoint aceita um único parâmetro de consulta e retorna uma resposta JSON estruturada. Qualquer agente Paperclip que possa fazer uma requisição HTTP GET - incluindo o tipo de agente HTTP integrado - pode chamar esses endpoints diretamente.

O padrão mais natural é um Agente de Qualidade de Dados dedicado que fica entre a entrada bruta (envios de formulários, importações de CRM, eventos de webhook) e os agentes que agem sobre esses dados (contatos, faturamento, provisionamento). Pense nele como uma camada de filtro no seu org chart.

Caso de uso 1 - Qualificação de leads

Cenário: Seu agente CMO gerencia campanhas de saída. Os leads chegam por meio de formulários, arquivos CSV importados ou integrações de terceiros. Antes de passar qualquer lead para o agente de contato, uma verificação de qualidade de dados remove endereços que nunca irão converter.

Posição no org chart: Entre a etapa de importação do CRM e o agente de contato.

Chamadas Veille:

  • GET /v1/intelligence/email?query={{email}} - verificar disposable e risk_score
  • GET /v1/intelligence/domain?query={{domain}} - verificar domain_age_days para domínios registrados recentemente

Lógica de decisão:

IF email.disposable == true        → descartar lead
IF email.risk_score >= 75          → descartar lead
IF domain.domain_age_days < 30     → marcar para revisão manual
ELSE                               → passar para o agente de contato

Configuração de heartbeat: Execute a verificação como um heartbeat no Agente de Qualidade de Dados sempre que novos leads chegarem, ou em um agendamento (a cada 4 horas, toda noite antes do lote de contatos ser executado).

Fluxo de tickets:

[CRM Import Agent]
  cria ticket → "Novo lote de leads: 240 registros"
        ↓
[Data Quality Agent]
  valida cada email via API Veille
  cria ticket → "Lote limpo: 198 aprovados, 42 descartados"
        ↓
[Outreach Agent]
  processa 198 leads verificados

Um único ticket Paperclip registra cada chamada à API Veille e seu resultado. O log de auditoria mostra exatamente qual lead foi descartado e por quê - disposable: true, risk_score: 91 ou domain_age_days: 3.

Caso de uso 2 - Detecção de fraude em cadastros

Cenário: Sua plataforma oferece um teste gratuito. Um agente de automação de cadastros provisiona novas contas. Sem uma etapa de validação, emails descartáveis e IPs VPN podem criar contas falsas ilimitadas, esgotar recursos do período de teste e distorcer métricas de ativação.

Posição no org chart: Entre o receptor de webhook e o agente de provisionamento.

Chamadas Veille:

  • GET /v1/intelligence/email?query={{email}} - verificar disposable, risk_score, smtp_valid
  • GET /v1/intelligence/ip?query={{ip}} - verificar is_vpn, is_proxy, threat_score

Lógica de pontuação composta:

composite = (
    email["risk_score"] * 0.60
    + ip["threat_score"] * 0.40
)

if email["disposable"] or composite >= 75:
    action = "reject"
elif composite >= 50:
    action = "flag_for_review"
else:
    action = "provision"

Essa lógica é executada dentro do Agente de Qualidade de Dados antes que qualquer ticket de provisionamento seja criado. O agente publica o resultado como um comentário de ticket com a resposta completa da API anexada para rastreabilidade.

Para um guia completo deste padrão de detecção, veja Bloqueando Emails Descartáveis no OpenClaw - os mesmos endpoints Veille funcionam em qualquer agente com capacidade HTTP, incluindo OpenClaw dentro do Paperclip.

Caso de uso 3 - Validação financeira

Cenário: Seu agente de faturamento ou pagamento processa números IBAN e CNPJ/VAT durante o onboarding B2B. IBANs inválidos causam transferências com falha. Números de VAT inativos criam problemas de conformidade fiscal.

Posição no org chart: O agente de faturamento chama a Veille diretamente antes de gravar os dados de pagamento.

Chamadas Veille:

  • GET /v1/vat/iban?query={{iban}} - verificar valid, in_sepa_zone, bank_name
  • GET /v1/vat?query={{vat_number}} - verificar valid, company_name, country_code

Lógica de decisão:

IF iban.valid == false               → rejeitar configuração de pagamento, notificar COO
IF iban.in_sepa_zone == false        → sinalizar: transferência não SEPA requer aprovação manual
IF vat.valid == false                → aplicar alíquota de VAT local, não aplicar reversão de encargo
IF vat.country_code != customer.country → sinalizar para revisão de conformidade
ELSE                                 → prosseguir com o onboarding

Exemplo de ticket:

#1087 - Fazer onboarding do novo cliente: Acme GmbH
Agente de Faturamento - Em andamento

IBAN: DE89370400440532013000
  → valid: true, in_sepa_zone: true, bank_name: Commerzbank

VAT: DE123456789
  → valid: true, company_name: Acme GmbH, country_code: DE

Resultado: onboarding aprovado, reversão de encargo aplicada.

Cada resultado de validação faz parte do thread do ticket e do log de auditoria imutável. Se uma revisão de conformidade exigir prova de que um número de VAT estava ativo no momento do onboarding, os dados estarão lá.

Configurar o agente HTTP

O Paperclip suporta qualquer agente que possa receber um heartbeat. Para chamadas à API Veille, a configuração mais simples usa um agente Bash ou HTTP.

SKILLS.md para o Agente de Qualidade de Dados:

# Data Quality Agent

## Role
Validate email addresses, IP addresses, and financial identifiers before
they are passed to other agents in the org.

## Veille API
Base URL: https://api.veille.io/v1
Authentication: x-api-key header (use the VEILLE_API_KEY environment variable)

## Endpoints available
- Email validation: GET /v1/intelligence/email?query={email}
- Domain validation: GET /v1/intelligence/domain?query={domain}
- IP validation: GET /v1/intelligence/ip?query={ip}
- IBAN validation: GET /v1/vat/iban?query={iban}
- VAT validation: GET /v1/vat?query={vat_number}

## Decision thresholds
- email.disposable == true → discard
- email.risk_score >= 75 → discard
- email.risk_score 50–74 → flag for review
- ip.is_vpn or ip.is_proxy → flag for review
- ip.threat_score >= 75 → discard
- iban.valid == false → reject
- vat.valid == false → do not apply reverse charge

## Output
Post results as a ticket comment with the full API response.
Create a summary line: "Validated: {result} - {reason}".

Exemplo de chamada com agente Bash:

#!/bin/bash
# Executado pelo Agente de Qualidade de Dados no heartbeat

EMAIL=$1
API_KEY=$VEILLE_API_KEY

response=$(curl -s \
  "https://api.veille.io/v1/intelligence/email?query=${EMAIL}" \
  -H "x-api-key: ${API_KEY}")

disposable=$(echo "$response" | jq -r '.disposable')
risk_score=$(echo "$response" | jq -r '.risk_score')

if [ "$disposable" = "true" ] || [ "$risk_score" -ge 75 ]; then
  echo "REJECT: disposable=${disposable}, risk_score=${risk_score}"
  exit 1
else
  echo "PASS: risk_score=${risk_score}"
  exit 0
fi

O código de saída indica ao Paperclip se deve continuar o fluxo de trabalho (0) ou parar e criar um ticket de revisão (1).

Padrão de org chart

Uma empresa Paperclip que usa validação Veille em múltiplos fluxos de trabalho pode ter este aspecto:

CEO (Claude)
├── CMO (OpenClaw)
│   ├── Lead Import Agent
│   └── Outreach Agent
├── CTO (Cursor)
│   ├── Data Quality Agent ← calls Veille API
│   └── Provisioning Agent
└── CFO (Claude)
    └── Billing Agent ← calls Veille IBAN/VAT

O Agente de Qualidade de Dados serve a múltiplas equipes: ele valida leads para o pipeline de contatos do CMO e valida cadastros para o fluxo de provisionamento do CTO. Um agente, uma linha de orçamento, lógica de validação centralizada.

Visibilidade de custos

O Paperclip rastreia o custo por agente. As chamadas à API Veille têm um custo previsível por requisição, então você pode estimar o orçamento mensal do Agente de Qualidade de Dados com base no volume esperado.

Por exemplo, se sua plataforma processa 10.000 cadastros por mês e você faz duas chamadas a endpoints Veille por cadastro (email + IP), você sabe exatamente quantas requisições de API orçar. Defina o limite de gasto mensal do agente no Paperclip de acordo. Quando o agente atingir o limite, ele para automaticamente - sem excessos.

Artigos relacionados

Posts relacionados

Segurança

Lista de domínios de email descartáveis: como bloqueá-los

Obtenha a lista atualizada de domínios de email descartáveis. Compare as melhores blocklists, APIs e exemplos de código para proteger seus cadastros e reputação de envio.

Leia mais
Segurança

Bloquear emails descartáveis no OpenClaw

Adicione detecção de emails descartáveis a qualquer workflow do OpenClaw usando a API Veille. Configuração passo a passo, lógica de decisão e padrões de automação comuns.

Leia mais
Engenharia

Como construímos um dataset de emails descartáveis

Navegadores headless, capturas de tela, OCR, pipelines de validação: um olhar técnico sobre como construímos o dataset por trás da nossa API de detecção de emails descartáveis.

Leia mais