Endpoint de Identificación

El endpoint /api/visitors/identify permite vincular un visitante anónimo con información de identificación conocida, como un ID de lead, correo electrónico o cualquier otro identificador personalizado. Esto permite unificar el seguimiento entre sesiones, dispositivos y estados de autenticación.

Especificación de la API

• URL: /api/visitors/identify
• Método: POST
• Formato de datos: JSON
• Autenticación: API Key en encabezado X-SA-API-KEY

Parámetros del Request

Estructura de traits

El objeto traits puede incluir cualquier propiedad para identificar y enriquecer el perfil del lead:

{
  "email": "email@ejemplo.com",
  "phone": "+34123456789",
  "name": "Nombre Completo",
  "first_name": "Nombre",
  "last_name": "Apellido",
  "gender": "female",
  "age": 32,
  "birthday": "1990-01-15",
  "social_networks": {
    "facebook": "username",
    "twitter": "username",
    "instagram": "username",
    "linkedin": "username",
    "github": "username",
    "youtube": "username",
    "tiktok": "username"
  },
  "address": {
    "street": "Calle Principal 123",
    "city": "Madrid",
    "state": "Madrid",
    "postalCode": "28001",
    "country": "España"
  },
  "company": {
    "name": "Empresa SA",
    "industry": "Tecnología",
    "employee_count": 120
  },
  "subscription": {
    "plan": "premium",
    "status": "active",
    "started_at": "2023-01-01"
  }
}

Ejemplo de payload

Identificación básica

{
  "site_id": "site_123abc",
  "visitor_id": "vis_abcd1234",
  "lead_id": "lead_5678",
  "segment_id": "seg_premium",
  "timestamp": 1646123456789
}

Identificación con atributos detallados

{
  "site_id": "site_123abc",
  "visitor_id": "vis_abcd1234",
  "lead_id": "lead_5678",
  "segment_id": "seg_premium_users",
  "traits": {
    "email": "usuario@ejemplo.com",
    "phone": "+34612345678",
    "name": "Ana García",
    "first_name": "Ana",
    "last_name": "García",
    "social_networks": {
      "linkedin": "ana-garcia",
      "twitter": "anagarcia",
      "github": "anagarcia"
    },
    "subscription": {
      "plan": "premium",
      "status": "active",
      "started_at": "2023-06-15"
    },
    "company": {
      "name": "Empresa Innovadora SL",
      "role": "Marketing Manager"
    }
  },
  "timestamp": 1646123456789
}

Respuesta

{
  "success": true,
  "visitor_id": "vis_abcd1234",
  "lead_id": "lead_5678",
  "segment_id": "seg_premium_users",
  "profile_id": "prof_987654",
  "merged": true,
  "merged_ids": ["vis_previous1", "vis_previous2"]
}

Códigos de estado HTTP

• 200 OK: Identificación exitosa
• 400 Bad Request: Parámetros inválidos o faltantes
• 401 Unauthorized: API key inválida o faltante
• 403 Forbidden: El sitio no tiene permisos para usar esta funcionalidad
• 429 Too Many Requests: Se ha excedido el límite de peticiones
• 500 Internal Server Error: Error en el servidor

Gestión de errores

En caso de error, la respuesta incluirá detalles sobre el problema:

{
  "success": false,
  "error": {
    "code": "invalid_parameters",
    "message": "Se debe proporcionar al menos lead_id o traits",
    "details": {
      "missing_fields": ["lead_id or traits"]
    }
  }
}

Fusión de perfiles

Cuando un visitante anónimo se identifica con un lead_id que ya existe, los perfiles se fusionan automáticamente:

1. Se crea un perfil unificado (si no existe)
2. Se vinculan todos los visitor_id al mismo perfil
3. El historial de eventos y sesiones de todos los perfiles vinculados se unifica
4. Las propiedades de los perfiles se combinan, dando prioridad a los datos más recientes

Propiedades reservadas

Algunas propiedades en traits tienen un significado especial y se mapean directamente a columnas en la base de datos:

Estructura de social_networks

El objeto social_networks puede incluir los siguientes campos:

Actualización de propiedades

Cada vez que se llama al endpoint identify, las propiedades del lead se actualizan:

• Las propiedades nuevas se añaden
• Las propiedades existentes se sobrescriben con los nuevos valores
• Las propiedades que no se incluyen en el request no se modifican

ID Unification y Cross-Device Tracking

La identificación permite vincular múltiples dispositivos y sesiones al mismo lead:

1. Navegación en diferentes dispositivos: Cuando un lead inicia sesión desde distintos dispositivos, todos sus visitor_id se vinculan al mismo lead_id

2. Tracking anónimo e identificado: El historial de navegación anónima se conserva y vincula al perfil cuando el lead se identifica

3. Reconexión de perfiles: Si un lead elimina cookies y regresa, el perfil se reconecta al identificarse nuevamente

Límites y cuotas

• Tamaño máximo de payload: 100KB
• Propiedades máximas en traits: 100
• Peticiones por minuto: 100 por IP
• Profundidad máxima de objetos anidados: 5 niveles

Buenas prácticas

1. Identificar lo antes posible: Llama al endpoint identify tan pronto como tengas información del lead (login, registro, etc.)

2. Mantener consistencia: Usa los mismos identificadores y estructura de traits en todas tus aplicaciones

3. Identificación progresiva: Actualiza gradualmente el perfil del lead a medida que recopiles más información

4. Privacidad de datos: Solo recopila y envía los datos necesarios respetando las políticas de privacidad

5. Consistencia en campos clave: Usa formatos estándar para email, teléfono, fechas y otros datos estructurados

Prueba el endpoint

Puedes probar el endpoint directamente desde aquí: