Awenlytics / API Docs
Iniciar sesión

API de Awenlytics

Integra tu CRM, sitio web o cualquier sistema con Awenlytics para sincronizar leads y conversiones.

Quick Start

1. Base URL

https://awenlytics.com/api/v1

2. Autenticación

Incluye tu API Key en el header de cada request:

Authorization: Bearer TU_API_KEY

3. Obtener tu API Key

Ve a Configuración → API Keys en tu cuenta de Awenlytics para crear una API Key.

Endpoints

POST /leads Crear un nuevo lead

Crea un lead desde tu formulario web o CRM. Awenlytics lo asociará automáticamente al ad/campaña correspondiente usando los click IDs o parámetros UTM.

Request Body

{
  // Datos de contacto
  "email": "cliente@ejemplo.com",
  "phone": "+521234567890",
  "name": "Juan Pérez",
  "company": "Empresa SA",

  // ID de tu CRM (para sincronización bidireccional)
  "external_crm_id": "CRM-12345",

  // Click IDs (capturados de la URL)
  "fbclid": "AbCdEf123456...",   // Facebook
  "gclid": "CjwKCAjw...",        // Google
  "ttclid": "E.CP...",           // TikTok

  // IDs de la plataforma (opcional, para match directo)
  "external_ad_id": "120212345678",
  "external_adset_id": "120298765432",
  "external_campaign_id": "120213456789",

  // UTM parameters
  "utm_source": "facebook",
  "utm_medium": "cpc",
  "utm_campaign": "promo_enero",
  "utm_content": "120212345678",  // Puedes poner el ad_id aquí

  // Datos del navegador (mejora atribución)
  "landing_page_url": "https://tu-web.com/landing?fbclid=...",
  "ip_address": "189.123.45.67",
  "user_agent": "Mozilla/5.0...",
  "fb_browser_id": "_fbp cookie",  // Cookie _fbp de Facebook
  "fb_click_id": "_fbc cookie",    // Cookie _fbc de Facebook

  // Campos personalizados
  "custom_fields": {
    "producto_interes": "Plan Pro",
    "presupuesto": "10000"
  }
}

Response

{
  "success": true,
  "message": "Lead created successfully",
  "data": {
    "id": 456,
    "email": "cliente@ejemplo.com",
    "status": "new",
    "campaign_id": 12,
    "adset_id": 34,
    "ad_id": 56,
    ...
  },
  "attribution": {
    "matched_by": "external_ad_id",
    "campaign": "Promo Enero 2026",
    "adset": "Audiencia Lookalike",
    "ad": "Video Testimonial"
  }
}
PATCH /leads/{id} Actualizar un lead

Actualiza el status de un lead. Cuando cambias a won, Awenlytics envía automáticamente la conversión a Facebook/Google/TikTok.

Request Body

{
  "status": "won",           // new, contacted, qualified, interested, negotiation, won, lost
  "sale_value": 15000.00,    // Valor de la venta (para calcular ROAS)
  "notes": "Cliente compró plan premium",
  "external_crm_id": "CRM-12345"
}

Response

{
  "success": true,
  "message": "Lead updated successfully",
  "data": {
    "id": 456,
    "status": "won",
    "sale_value": 15000.00,
    "converted_at": "2026-01-19T18:30:00Z",
    "conversion_sent_facebook": true,
    ...
  }
}

Conversión automática: Cuando el status cambia a "won" y el lead tiene un fbclid, la conversión se envía automáticamente a Facebook Conversions API.

GET /leads Listar leads

Obtiene la lista de leads de tu organización con filtros opcionales.

Query Parameters

Parámetro Descripción
status Filtrar por status (new, contacted, won, etc.)
source_platform Filtrar por plataforma (facebook, google, tiktok)
from_date Fecha desde (YYYY-MM-DD)
to_date Fecha hasta (YYYY-MM-DD)
search Buscar por nombre, email o teléfono
per_page Resultados por página (default: 50)
GET /leads/find-by-crm-id Buscar por ID de CRM

Busca un lead usando el ID de tu CRM.

Query Parameters

GET /leads/find-by-crm-id?external_crm_id=CRM-12345
GET /me Info de la organización

Verifica tu API Key y obtiene información de tu organización. 

{
  "success": true,
  "data": {
    "organization": {
      "id": 1,
      "name": "Mi Empresa"
    },
    "token": {
      "name": "CRM Integration",
      "last_used_at": "2026-01-19T18:00:00Z"
    }
  }
}

Guía de Atribución

Awenlytics intenta asociar cada lead con el ad/campaña correcto usando esta prioridad:

  1. external_ad_id - Match exacto con el ID del ad en Facebook/Google
  2. external_adset_id - Match con el ID del conjunto de anuncios
  3. external_campaign_id - Match con el ID de la campaña
  4. utm_content - Si contiene el ad_id, hace match
  5. utm_campaign - Busca campaña por nombre

Configuración recomendada de UTMs en tus ads:

https://tu-web.com/landing?utm_source=facebook&utm_medium=cpc&utm_campaign={{campaign.name}}&utm_content={{ad.id}}

Tip: Aunque no logres hacer match directo, si el lead tiene fbclid, cuando se convierta, Facebook recibirá la conversión y hará la atribución internamente.

Flujo de Status

new → contacted → qualified → interested → negotiation → won
or
lost

Ejemplos de Código

PHP (cURL)

<?php
$apiKey = 'TU_API_KEY';
$baseUrl = 'https://awenlytics.com/api/v1';

// Crear lead
$data = [
    'email' => 'cliente@ejemplo.com',
    'name' => 'Juan Pérez',
    'fbclid' => $_GET['fbclid'] ?? null,
    'utm_campaign' => $_GET['utm_campaign'] ?? null,
    'external_crm_id' => 'CRM-12345',
];

$ch = curl_init("$baseUrl/leads");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json',
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

// Guardar el ID de Awenlytics para actualizaciones futuras
$awenlyticsLeadId = $result['data']['id'];

JavaScript (Fetch)

const API_KEY = 'TU_API_KEY';
const BASE_URL = 'https://awenlytics.com/api/v1';

// Crear lead
async function createLead(leadData) {
  const response = await fetch(`${BASE_URL}/leads`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(leadData),
  });
  return response.json();
}

// Actualizar status
async function updateLeadStatus(leadId, status, saleValue = null) {
  const response = await fetch(`${BASE_URL}/leads/${leadId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ status, sale_value: saleValue }),
  });
  return response.json();
}

Códigos de Error

Código Descripción
401 API Key inválida o faltante
403 API Key no tiene permisos para esta acción
404 Recurso no encontrado
422 Error de validación (revisa los campos enviados)
500 Error interno del servidor