Usare l'API Veille in un'azienda autonoma Paperclip

Paperclip è una piattaforma open-source per gestire aziende AI autonome. Si definisce un obiettivo, si assumono agenti - Claude, Codex, OpenClaw o qualsiasi bot compatibile HTTP - li si organizza in un org chart e li si lascia lavorare. I heartbeat svegliano gli agenti secondo un calendario. I ticket registrano ogni decisione. I budget limitano quanto ogni agente può spendere.

Quando questi agenti toccano dati utente - iscrizioni, lead, pagamenti, outreach - devono validare ciò che ricevono. Un flusso di qualificazione dei lead gestito da AI che elabora email non verificate produce rumore. Un agente di fatturazione che accetta IBAN non controllati genererà transazioni fallite. Un'automazione delle iscrizioni che ignora gli indirizzi email usa e getta gonfierà le metriche di conversione con account fantasma.

Questo articolo mostra come collegare l'API Veille agli agenti Paperclip per aggiungere controlli di qualità dei dati in ogni fase di un'azienda autonoma.

Dove si inserisce Veille in un'azienda Paperclip

Veille offre quattro endpoint di validazione:

Endpoint	Cosa valida
`GET /v1/intelligence/email`	Rilevamento usa e getta, punteggio di rischio, verifica SMTP
`GET /v1/intelligence/domain`	Età del dominio, DNS, segnali di minaccia
`GET /v1/intelligence/ip`	VPN/proxy/Tor, punteggio di minaccia, geolocalizzazione
`GET /v1/vat/iban`	Validità IBAN, BIC, nome della banca, appartenenza SEPA

Ogni endpoint accetta un singolo parametro di query e restituisce una risposta JSON strutturata. Qualsiasi agente Paperclip in grado di effettuare una richiesta HTTP GET - incluso il tipo di agente HTTP integrato - può chiamarli direttamente.

Il pattern più naturale è un Agente per la Qualità dei Dati dedicato che si posiziona tra l'input grezzo (invii di moduli, importazioni CRM, eventi webhook) e gli agenti che agiscono su quei dati (outreach, fatturazione, provisioning). Pensate ad esso come uno strato filtrante nel vostro org chart.

Caso d'uso 1 - Qualificazione dei lead

Scenario: Il vostro agente CMO gestisce campagne in uscita. I lead arrivano tramite moduli, file CSV importati o integrazioni di terze parti. Prima di passare qualsiasi lead all'agente di outreach, un controllo della qualità dei dati rimuove gli indirizzi che non convertiranno mai.

Posizione nell'org chart: Tra il passaggio di importazione CRM e l'agente di outreach.

Chiamate Veille:

GET /v1/intelligence/email?query={{email}} - controlla disposable e risk_score
GET /v1/intelligence/domain?query={{domain}} - controlla domain_age_days per domini registrati di recente

Logica decisionale:

IF email.disposable == true        → scarta il lead
IF email.risk_score >= 75          → scarta il lead
IF domain.domain_age_days < 30     → segnala per revisione manuale
ELSE                               → passa all'agente di outreach

Configurazione heartbeat: Esegui il controllo come heartbeat sull'Agente per la Qualità dei Dati ogni volta che arrivano nuovi lead, o secondo un calendario (ogni 4 ore, ogni notte prima dell'esecuzione del batch di outreach).

Flusso dei ticket:

[Agente Importazione CRM]
  crea ticket → "Nuovo batch di lead: 240 record"
        ↓
[Agente Qualità Dati]
  valida ogni email tramite API Veille
  crea ticket → "Batch pulito: 198 approvati, 42 scartati"
        ↓
[Agente Outreach]
  elabora 198 lead verificati

Un singolo ticket Paperclip registra ogni chiamata API Veille e il suo risultato. Il registro di audit mostra esattamente quale lead è stato scartato e perché - disposable: true, risk_score: 91, o domain_age_days: 3.

Caso d'uso 2 - Rilevamento frodi nelle iscrizioni

Scenario: La vostra piattaforma offre una prova gratuita. Un agente di automazione delle iscrizioni fornisce nuovi account. Senza un passaggio di validazione, email usa e getta e IP VPN possono creare account falsi illimitati, prosciugare le risorse di prova e distorcere le metriche di attivazione.

Posizione nell'org chart: Tra il ricevitore del webhook e l'agente di provisioning.

Chiamate Veille:

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

Logica di punteggio composita:

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"

Questa logica viene eseguita all'interno dell'Agente per la Qualità dei Dati prima che venga creato qualsiasi ticket di provisioning. L'agente pubblica il risultato come commento al ticket con la risposta API completa allegata per la tracciabilità.

Per una guida completa su questo schema di rilevamento, vedere Bloccare le Email Usa e Getta in OpenClaw - gli stessi endpoint Veille funzionano in qualsiasi agente compatibile HTTP, incluso OpenClaw all'interno di Paperclip.

Caso d'uso 3 - Validazione finanziaria

Scenario: Il vostro agente di fatturazione o pagamenti elabora numeri IBAN e IVA durante l'onboarding B2B. IBAN non validi causano trasferimenti falliti. Numeri IVA inattivi creano problemi di conformità fiscale.

Posizione nell'org chart: L'agente di fatturazione chiama Veille direttamente prima di scrivere i dati di pagamento.

Chiamate Veille:

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

Logica decisionale:

IF iban.valid == false               → rifiuta configurazione pagamento, notifica COO
IF iban.in_sepa_zone == false        → segnala: trasferimento non-SEPA richiede approvazione manuale
IF vat.valid == false                → applica aliquota IVA locale, non applicare inversione contabile
IF vat.country_code != customer.country → segnala per revisione conformità
ELSE                                 → procedi con l'onboarding

Esempio di ticket:

#1087 - Onboard nuovo cliente: Acme GmbH
Agente Fatturazione - In corso

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

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

Risultato: onboarding approvato, inversione contabile applicata.

Ogni risultato di validazione fa parte del thread del ticket e del registro di audit immutabile. Se una revisione di conformità richiede mai la prova che un numero IVA era attivo al momento dell'onboarding, i dati sono lì.

Configurare l'agente HTTP

Paperclip supporta qualsiasi agente in grado di ricevere un heartbeat. Per le chiamate API Veille, la configurazione più semplice utilizza un agente Bash o HTTP.

SKILLS.md per l'Agente Qualità Dati:

# Agente Qualità Dati

## Ruolo
Valida indirizzi email, indirizzi IP e identificatori finanziari prima
che vengano passati ad altri agenti nell'organizzazione.

## API Veille
URL base: https://api.veille.io/v1
Autenticazione: header x-api-key (usa la variabile d'ambiente VEILLE_API_KEY)

## Endpoint disponibili
- Validazione email: GET /v1/intelligence/email?query={email}
- Validazione dominio: GET /v1/intelligence/domain?query={domain}
- Validazione IP: GET /v1/intelligence/ip?query={ip}
- Validazione IBAN: GET /v1/vat/iban?query={iban}
- Validazione IVA: GET /v1/vat?query={vat_number}

## Soglie decisionali
- email.disposable == true → scarta
- email.risk_score >= 75 → scarta
- email.risk_score 50–74 → segnala per revisione
- ip.is_vpn or ip.is_proxy → segnala per revisione
- ip.threat_score >= 75 → scarta
- iban.valid == false → rifiuta
- vat.valid == false → non applicare inversione contabile

## Output
Pubblica i risultati come commento al ticket con la risposta API completa.
Crea una riga di riepilogo: "Validato: {risultato} - {motivo}".

Esempio di chiamata agente Bash:

#!/bin/bash
# Eseguito dall'Agente Qualità Dati al 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

Il codice di uscita segnala a Paperclip se continuare il flusso di lavoro (0) o fermarsi e creare un ticket di revisione (1).

Schema dell'org chart

Un'azienda Paperclip che utilizza la validazione Veille in più flussi di lavoro potrebbe assomigliare a questo:

CEO (Claude)
├── CMO (OpenClaw)
│   ├── Agente Importazione Lead
│   └── Agente Outreach
├── CTO (Cursor)
│   ├── Agente Qualità Dati ← chiama API Veille
│   └── Agente Provisioning
└── CFO (Claude)
    └── Agente Fatturazione ← chiama Veille IBAN/VAT

L'Agente per la Qualità dei Dati serve più team: valida i lead per la pipeline di outreach del CMO e valida le iscrizioni per il flusso di provisioning del CTO. Un agente, una voce di budget, logica di validazione centralizzata.

Visibilità dei costi

Paperclip traccia il costo per agente. Le chiamate API Veille hanno un costo prevedibile per richiesta, quindi puoi stimare il budget mensile dell'Agente per la Qualità dei Dati in base al volume previsto.

Ad esempio, se la vostra piattaforma elabora 10.000 iscrizioni al mese e chiamate due endpoint Veille per iscrizione (email + IP), sapete esattamente quante richieste API includere nel budget. Impostate di conseguenza il limite di spesa mensile dell'agente in Paperclip. Quando l'agente raggiunge il limite, si ferma automaticamente - nessun sforamento.

Usare l'API Veille in un'azienda autonoma Paperclip

Dove si inserisce Veille in un'azienda Paperclip

Caso d'uso 1 - Qualificazione dei lead

Caso d'uso 2 - Rilevamento frodi nelle iscrizioni

Caso d'uso 3 - Validazione finanziaria

Configurare l'agente HTTP

Schema dell'org chart

Visibilità dei costi

Articoli correlati

Articoli correlati

Lista dei domini email usa e getta: come bloccarli

Bloccare le email usa e getta in OpenClaw

Come abbiamo costruito un dataset di email usa e getta