Documentación de la API

Introducción

La API REST de Affino permite integrar la plataforma de captación comercial con sistemas externos: CRMs, ERPs, formularios web, herramientas de scraping o servicios de enriquecimiento de datos. A través de la API puedes:

• Importar y actualizar prospectos en bloque, con fusión inteligente de datos cuando el contacto ya existe.
• Añadir emails o dominios completos a la lista de bajas (lista negra) para evitar futuros envíos.

Todas las peticiones y respuestas utilizan formato JSON y codificación UTF-8.

Autenticación y contexto

Todas las rutas de la API requieren autenticación mediante una clave de API (Bearer Token) y la especificación del usuario destino. Ambos valores se envían como cabeceras HTTP en cada petición.

El valor de X-User-ID se valida contra el sistema de autenticación de Affino. Si el usuario no existe, la petición se rechaza con código 403 Forbidden.

1. Importación de prospectos

Añade o actualiza prospectos en bloque. Si el email ya existe, los datos se fusionan inteligentemente.

Cabeceras

Authorization: Bearer <TU_API_KEY>
X-User-ID: <UID_DEL_USUARIO>
Content-Type: application/json

Cuerpo de la petición

El cuerpo debe ser un array de objetos JSON. Las claves deben estar en minúsculas exactas y sin acentos (salvo campaña, que lleva la ñ).

Cualquier clave adicional no listada arriba se guardará automáticamente dentro del campo notas como JSON.

Ejemplo de petición

[
  {
    "nombre": "Ana García",
    "email": "ana.garcia@tecnosol.com",
    "empresa": "TecnoSoluciones",
    "cargo": "directora de marketing",
    "productos": "servicio cloud, soporte premium"
  }
]

Comportamiento

• Crear vs. actualizar: si el email ya existe, el prospecto se actualiza (fusión de datos; los productos se combinan sin duplicar). Si no existe, se crea.
• Campaña inexistente — no bloquea la fila: si el valor de campaña no coincide con ninguna campaña existente del usuario, el prospecto se importa igualmente pero sin asignar campaña, y se añade un aviso a errorDetails. Las campañas no se crean automáticamente.
• Categorías nuevas: los valores de sector, vertical, productos y cargo que no existían se añaden automáticamente a la configuración del usuario.
• Emails inválidos: las filas con un email mal formado (sin @ o sin punto en el dominio) se omiten, con un aviso en errorDetails.
• Tope de contactos según tu plan: al alcanzar el límite del plan, los prospectos nuevos excedentes se omiten (no se crean); las actualizaciones de existentes no cuentan para el tope. La respuesta incluye entonces limitReached: true y skipped: <N>, más un aviso en errorDetails.

Respuestas

Ejemplo de respuesta (200 OK)

{
  "message": "Importación procesada correctamente.",
  "created": 12,
  "updated": 3,
  "errors": 1,
  "errorDetails": [
    "Email x@y.com: La campaña 'Z' no existe y no se asignará."
  ]
}

errors es el número de avisos; created y updated pueden ser mayores que 0 aunque haya avisos. Si se alcanzó el tope de contactos del plan, se añaden los campos limitReached y skipped.

2. Añadir a la lista de bajas

Añade emails (o dominios completos) a la lista negra para evitar futuros envíos.

Cuerpo de la petición

El cuerpo debe ser un array de strings. Cada string puede ser:

• Un email concreto: "email.a.bloquear@dominio.com".
• Un dominio completo, anteponiendo @: "@dominio.com" bloquea todos los emails de ese dominio (se almacena sin la @).

Ejemplo de petición

[
  "email.a.bloquear@dominio.com",
  "@competencia.com"
]

Cada valor se normaliza a minúsculas. Se descartan (con aviso) los valores sin un . o con espacios.

Respuestas

Ejemplo de respuesta (200 OK)

{
  "message": "Lista de bajas procesada correctamente.",
  "imported": 2,
  "errors": 0,
  "errorDetails": []
}

Códigos de error generales

Soporte

Si tienes dudas durante la integración o necesitas una clave de API, contacta con el equipo de Affino y te la haremos llegar junto con tu X-User-ID.