Skip to main content

CDP Enterprise API Reference

Base URL​

Production: https://nerdistan-datalake-production.up.railway.app

Authentication​

Actualmente la API está en modo desarrollo. La autenticación JWT será implementada en producción.

Endpoints​

Health Check​

Verifica el estado del sistema y la conexión a la base de datos.

GET /health

Response​

{
  "success": true,
  "message": "System operational",
  "data": {
    "database": "connected",
    "profiles": 202808,
    "timestamp": "2025-09-19T01:43:39.174160"
  }
}

Single Event Ingestion​

Ingesta un evento único en tiempo real.

POST /api/v2/cdp/events

Request Body​

{
  "tenant_id": 56,
  "customer_id": 12345,
  "profile_id": null,  // Opcional
  "event_type": "product_view",
  "event_data": {
    "product_id": "SKU123",
    "product_name": "Test Product",
    "price": 99.99,
    "category": "Electronics"
  }
}

Response​

{
  "success": true,
  "message": "Event 7 ingested",
  "data": {
    "event_id": 7
  }
}

Event Types Soportados​

  • page_view - Vista de página
  • product_view - Vista de producto
  • add_to_cart - Agregar al carrito
  • remove_from_cart - Quitar del carrito
  • purchase - Compra completada
  • search - Búsqueda realizada
  • email_open - Email abierto
  • email_click - Click en email
  • custom - Evento personalizado

Batch Event Ingestion​

Ingesta múltiples eventos en una sola llamada (máximo 100).

POST /api/v2/cdp/events/batch

Request Body​

[
  {
    "tenant_id": 56,
    "customer_id": 12345,
    "event_type": "page_view",
    "event_data": {
      "page": "/home",
      "time_on_page": 30
    }
  },
  {
    "tenant_id": 56,
    "customer_id": 12346,
    "event_type": "add_to_cart",
    "event_data": {
      "product_id": "SKU456",
      "quantity": 2,
      "price": 49.99
    }
  }
]

Response​

{
  "success": true,
  "message": "Batch of 2 events ingested",
  "data": {
    "event_ids": [8, 9],
    "count": 2
  }
}

CDP Status​

Obtiene estadísticas y estado actual del CDP.

GET /api/v2/cdp/status

Response​

{
  "success": true,
  "message": "Status retrieved",
  "data": {
    "statistics": {
      "total_profiles": 202808,
      "pending_events": 0,
      "recent_events": 10,
      "active_tenants": 24
    },
    "top_tenants": [
      {
        "tenant_id": 56,
        "profiles": 89234
      },
      {
        "tenant_id": 42,
        "profiles": 45678
      }
    ],
    "timestamp": "2025-09-19T01:50:00.000000"
  }
}

Get Profile​

Obtiene información detallada de un perfil de cliente.

GET /api/v2/cdp/profiles/{profile_id}?tenant_id={tenant_id}

Parameters​

  • profile_id (path, required): ID del perfil
  • tenant_id (query, required): ID del tenant

Response​

{
  "success": true,
  "message": "Profile retrieved",
  "data": {
    "profile": {
      "profile_id": 12345,
      "customer_id": 67890,
      "email": "customer@example.com",
      "first_name": "Juan",
      "last_name": "Pérez",
      "lifecycle_stage": "active",
      "rfm_segment": "Champions",
      "historical_value": 5432.10,
      "days_since_last_order": 15
    },
    "recent_events": [
      {
        "event_type": "product_view",
        "event_data": {...},
        "created_at": "2025-09-19T00:30:00"
      }
    ]
  }
}

Error Responses​

Todos los endpoints siguen el mismo formato de error:

{
  "success": false,
  "message": "Error description",
  "data": null
}

Códigos de Estado HTTP​

CódigoDescripción
200Success
400Bad Request - Parámetros inválidos
404Not Found - Recurso no encontrado
422Unprocessable Entity - Validación fallida
500Internal Server Error

Rate Limiting​

Actualmente no hay límites de rate. En producción se implementará:

  • 1000 requests/minuto por IP
  • 10000 events/hora por tenant

Ejemplos con cURL​

Health Check​

curl https://nerdistan-datalake-production.up.railway.app/health

Enviar Evento​

curl -X POST https://nerdistan-datalake-production.up.railway.app/api/v2/cdp/events \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": 56,
    "customer_id": 12345,
    "event_type": "product_view",
    "event_data": {
      "product_id": "SKU123",
      "price": 99.99
    }
  }'

Batch de Eventos​

curl -X POST https://nerdistan-datalake-production.up.railway.app/api/v2/cdp/events/batch \
  -H "Content-Type: application/json" \
  -d '[
    {
      "tenant_id": 56,
      "customer_id": 12345,
      "event_type": "page_view",
      "event_data": {"page": "/home"}
    },
    {
      "tenant_id": 56,
      "customer_id": 12346,
      "event_type": "add_to_cart",
      "event_data": {"product_id": "SKU456", "quantity": 2}
    }
  ]'

SDK JavaScript (Ejemplo)​

class CDPClient {
  constructor(baseURL = 'https://nerdistan-datalake-production.up.railway.app') {
    this.baseURL = baseURL;
  }

  async sendEvent(tenantId, customerId, eventType, eventData) {
    const response = await fetch(`${this.baseURL}/api/v2/cdp/events`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        tenant_id: tenantId,
        customer_id: customerId,
        event_type: eventType,
        event_data: eventData
      })
    });
    return response.json();
  }

  async sendBatch(events) {
    const response = await fetch(`${this.baseURL}/api/v2/cdp/events/batch`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(events)
    });
    return response.json();
  }

  async getStatus() {
    const response = await fetch(`${this.baseURL}/api/v2/cdp/status`);
    return response.json();
  }

  async getProfile(profileId, tenantId) {
    const response = await fetch(
      `${this.baseURL}/api/v2/cdp/profiles/${profileId}?tenant_id=${tenantId}`
    );
    return response.json();
  }
}

// Uso
const cdp = new CDPClient();

// Enviar evento
cdp.sendEvent(56, 12345, 'product_view', {
  product_id: 'SKU123',
  price: 99.99
}).then(response => console.log(response));

Webhook Notifications (Próximamente)​

En futuras versiones, el CDP enviará webhooks para eventos importantes:

  • Cambio de segmento RFM
  • Entrada/salida de audiencia
  • Threshold de CLV alcanzado
  • Riesgo de churn detectado

Versionado​

La API usa versionado en la URL. La versión actual es v2.

Cambios breaking serán introducidos en nuevas versiones (v3, v4, etc).

Soporte​

Para soporte técnico o preguntas sobre la API: