Volver al blog
Engineering

Usar la API de Veille en una empresa autónoma de Paperclip

Josselin Liebe
Josselin Liebe

Paperclip es una plataforma de código abierto para ejecutar empresas autónomas de IA. Defines un objetivo, contratas agentes - Claude, Codex, OpenClaw o cualquier bot compatible con HTTP - los organizas en un org chart y los dejas trabajar. Los heartbeats despiertan a los agentes según un calendario. Los tickets registran cada decisión. Los presupuestos limitan lo que cada agente puede gastar.

Cuando esos agentes tocan datos de usuarios - registros, leads, pagos, contactos - necesitan validar lo que reciben. Un flujo de calificación de leads gestionado por IA que procesa emails no verificados generará ruido. Un agente de facturación que acepta IBANs sin verificar producirá transacciones fallidas. Una automatización de registros que ignora las direcciones de email desechables inflará tus métricas de conversión con cuentas fantasma.

Este artículo muestra cómo conectar la API de Veille a los agentes de Paperclip para añadir controles de calidad de datos en cada etapa de un negocio autónomo.

Dónde encaja Veille en una empresa Paperclip

Veille ofrece cuatro endpoints de validación:

Endpoint Qué valida
GET /v1/intelligence/email Detección de desechables, puntuación de riesgo, verificación SMTP
GET /v1/intelligence/domain Antigüedad del dominio, DNS, señales de amenaza
GET /v1/intelligence/ip VPN/proxy/Tor, puntuación de amenaza, geolocalización
GET /v1/vat/iban Validez del IBAN, BIC, nombre del banco, membresía SEPA

Cada endpoint acepta un único parámetro de consulta y devuelve una respuesta JSON estructurada. Cualquier agente de Paperclip que pueda hacer una solicitud HTTP GET - incluido el tipo de agente HTTP integrado - puede llamar a estos directamente.

El patrón más natural es un Agente de Calidad de Datos dedicado que se sitúa entre la entrada bruta (envíos de formularios, importaciones de CRM, eventos webhook) y los agentes que actúan sobre esos datos (contacto, facturación, aprovisionamiento). Piensa en él como una capa de filtro en tu org chart.

Caso de uso 1 - Calificación de leads

Escenario: Tu agente CMO gestiona campañas salientes. Los leads llegan a través de formularios, archivos CSV importados o integraciones de terceros. Antes de pasar cualquier lead al agente de contacto, una verificación de calidad de datos elimina las direcciones que nunca se convertirán.

Posición en el org chart: Entre el paso de importación del CRM y el agente de contacto.

Llamadas a Veille:

  • GET /v1/intelligence/email?query={{email}} - verificar disposable y risk_score
  • GET /v1/intelligence/domain?query={{domain}} - verificar domain_age_days para dominios registrados recientemente

Lógica de decisión:

IF email.disposable == true        → descartar lead
IF email.risk_score >= 75          → descartar lead
IF domain.domain_age_days < 30     → marcar para revisión manual
ELSE                               → pasar al agente de contacto

Configuración de heartbeat: Ejecuta la verificación como un heartbeat en el Agente de Calidad de Datos cada vez que lleguen nuevos leads, o según un calendario (cada 4 horas, cada noche antes de que se ejecute el lote de contactos).

Flujo de tickets:

[Agente de Importación CRM]
  crea ticket → "Nuevo lote de leads: 240 registros"
        ↓
[Agente de Calidad de Datos]
  valida cada email mediante la API de Veille
  crea ticket → "Lote limpiado: 198 aprobados, 42 descartados"
        ↓
[Agente de Contacto]
  procesa 198 leads verificados

Un único ticket de Paperclip registra cada llamada a la API de Veille y su resultado. El registro de auditoría muestra exactamente qué lead fue descartado y por qué - disposable: true, risk_score: 91 o domain_age_days: 3.

Caso de uso 2 - Detección de fraude en registros

Escenario: Tu plataforma ofrece una prueba gratuita. Un agente de automatización de registros aprovisiona nuevas cuentas. Sin un paso de validación, los emails desechables y las IPs VPN pueden crear cuentas falsas ilimitadas, agotar los recursos de prueba y distorsionar las métricas de activación.

Posición en el org chart: Entre el receptor de webhooks y el agente de aprovisionamiento.

Llamadas a 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 puntuación compuesta:

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"

Esta lógica se ejecuta dentro del Agente de Calidad de Datos antes de que se cree cualquier ticket de aprovisionamiento. El agente publica el resultado como un comentario de ticket con la respuesta completa de la API adjunta para mayor trazabilidad.

Para un recorrido completo de este patrón de detección, consulta Bloqueo de emails desechables en OpenClaw - los mismos endpoints de Veille funcionan en cualquier agente con capacidad HTTP, incluido OpenClaw dentro de Paperclip.

Caso de uso 3 - Validación financiera

Escenario: Tu agente de facturación o pagos procesa números IBAN y VAT durante el proceso de incorporación B2B. Los IBANs no válidos causan transferencias fallidas. Los números de IVA inactivos generan problemas de cumplimiento fiscal.

Posición en el org chart: El agente de facturación llama a Veille directamente antes de escribir los datos de pago.

Llamadas a 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 decisión:

IF iban.valid == false               → rechazar configuración de pago, notificar al COO
IF iban.in_sepa_zone == false        → marcar: transferencia no SEPA requiere aprobación manual
IF vat.valid == false                → aplicar tipo de IVA local, no aplicar inversión del sujeto pasivo
IF vat.country_code != customer.country → marcar para revisión de cumplimiento
ELSE                                 → proceder con la incorporación

Ejemplo de ticket:

#1087 - Incorporar nuevo cliente: Acme GmbH
Agente de Facturación - En progreso

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

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

Resultado: incorporación aprobada, inversión del sujeto pasivo aplicada.

Cada resultado de validación forma parte del hilo del ticket y del registro de auditoría inmutable. Si una revisión de cumplimiento requiere prueba de que un número de IVA estaba activo en el momento de la incorporación, los datos están ahí.

Configurar el agente HTTP

Paperclip admite cualquier agente que pueda recibir un heartbeat. Para las llamadas a la API de Veille, la configuración más sencilla utiliza un agente Bash o HTTP.

SKILLS.md para el Agente de Calidad de Datos:

# 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}".

Ejemplo de llamada con agente Bash:

#!/bin/bash
# Ejecutado por el Agente de Calidad de Datos en el 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

El código de salida indica a Paperclip si debe continuar el flujo de trabajo (0) o detenerse y crear un ticket de revisión (1).

Patrón de org chart

Una empresa Paperclip que utiliza la validación de Veille en múltiples flujos de trabajo podría tener 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

El Agente de Calidad de Datos sirve a múltiples equipos: valida leads para el pipeline de contacto del CMO y valida registros para el flujo de aprovisionamiento del CTO. Un agente, una línea de presupuesto, lógica de validación centralizada.

Visibilidad de costes

Paperclip rastrea el coste por agente. Las llamadas a la API de Veille tienen un coste predecible por solicitud, por lo que puedes estimar el presupuesto mensual del Agente de Calidad de Datos basándote en el volumen esperado.

Por ejemplo, si tu plataforma procesa 10.000 registros al mes y realizas dos llamadas a endpoints de Veille por registro (email + IP), sabes exactamente cuántas solicitudes de API presupuestar. Establece el límite de gasto mensual del agente en Paperclip en consecuencia. Cuando el agente alcanza el límite, se detiene automáticamente - sin desvíos.

Artículos relacionados

Artículos relacionados

Seguridad

Lista de dominios de emails desechables: cómo bloquearlos

Obtén la lista actualizada de dominios de emails desechables. Compara las mejores blocklists, APIs y ejemplos de código para proteger tus registros y tu reputación de envío.

Leer más
Seguridad

Bloquear emails desechables en OpenClaw

Añade detección de emails desechables a cualquier workflow de OpenClaw usando la API de Veille. Configuración paso a paso, lógica de decisión y casos de uso habituales.

Leer más
Engineering

Cómo construimos un dataset anti-emails desechables

Navegadores controlados, capturas de pantalla, OCR, pipelines de validación: así construimos el dataset que alimenta nuestra API de detección de emails desechables.

Leer más