CDP API v2 Reference

🌐 Base URLs

Production

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

Local Development

http://localhost:8000

🔐 Authentication

Currently, the API is open for internal use. Future versions will implement JWT authentication.

📊 Endpoints Overview

The CDP API v2 provides comprehensive endpoints for customer data management, analytics, and integrations.

Quick Links

CDP Processing
Analytics
Tenant Integrations
Customers
Events
Segments

CDP Processing

Process Tenant Data

Procesa análisis CDP (RFM, CLV, Churn) para un tenant específico.

POST /api/v2/cdp/process/{tenantId}

Parameters

tenantId (path, required): ID del tenant a procesar

Request Body

{
  "analyses": ["rfm", "clv", "churn"],
  "force": false
}

Response (200 OK)

{
  "success": true,
  "message": "CDP processing completed successfully",
  "tenant_id": 56,
  "results": {
    "rfm": {
      "total_processed": 65226,
      "segments": [
        {
          "segment": "Champions",
          "count": 16125,
          "percentage": 24.72
        }
      ],
      "processing_time": 45.2
    }
  }
}

Example

curl -X POST https://nerdistan-datalake-production.up.railway.app/api/v2/cdp/process/56 \
  -H "Content-Type: application/json" \
  -d '{"analyses": ["rfm"]}'

Get Processing Status

Obtiene el estado del procesamiento CDP para un tenant.

GET /api/v2/cdp/process/status/{tenantId}

Parameters

tenantId (path, required): ID del tenant

Response (200 OK)

{
  "status": "processed",
  "last_processed": "2024-09-16T19:16:45.665Z",
  "hours_since_last_sync": 2,
  "is_stale": false,
  "records_processed": "45282"
}

Analytics

RFM Analysis

Obtiene análisis RFM (Recency, Frequency, Monetary) para un tenant.

GET /api/v2/cdp/analytics/rfm

Query Parameters

tenant_id (required): ID del tenant
segment (optional): Filtrar por segmento específico
limit (optional): Número de resultados (default: 100)

Response (200 OK)

{
  "success": true,
  "message": "RFM analysis retrieved successfully",
  "data": {
    "overview": {
      "total_customers": 65226,
      "avg_recency": 428.01,
      "avg_frequency": 1.5,
      "avg_monetary": 2500.50,
      "total_revenue": 163065000,
      "last_calculation": "2024-09-16T19:16:40.897Z"
    },
    "distribution": [
      {
        "segment": "Champions",
        "customer_count": 16125,
        "percentage": 24.72,
        "avg_recency": 30,
        "avg_frequency": 5.2,
        "avg_monetary": 8500.00
      },
      {
        "segment": "Loyal Customers",
        "customer_count": 12500,
        "percentage": 19.17,
        "avg_recency": 45,
        "avg_frequency": 3.8,
        "avg_monetary": 5200.00
      }
    ],
    "segments": {
      "Champions": ["customer_id_1", "customer_id_2"],
      "Loyal Customers": ["customer_id_3", "customer_id_4"]
    }
  }
}

Segments Definition

Champions: Compraron recientemente, compran con frecuencia, gastan mucho
Loyal Customers: Gastan mucho dinero, responden a promociones
Potential Loyalists: Clientes recientes, gastaron cantidad considerable, compraron más de una vez
Recent Customers: Compraron recientemente, pero no frecuentemente
Promising: Compradores recientes, pero no han gastado mucho
Need Attention: Recencia, frecuencia y valores monetarios por encima del promedio
About to Sleep: Por debajo del promedio en recencia, frecuencia y monetario
At Risk: Gastaron mucho dinero y compraron con frecuencia, pero hace tiempo
Cannot Lose Them: Hicieron grandes compras y con frecuencia, pero hace mucho tiempo
Hibernating: Última compra hace mucho tiempo, bajos gastos y número de pedidos
Lost: Menor recencia, frecuencia y puntuación monetaria

Customer Lifetime Value (CLV)

Obtiene análisis de valor de vida del cliente.

GET /api/v2/cdp/analytics/clv

Query Parameters

tenant_id (required): ID del tenant
tier (optional): Filtrar por tier (high, medium, low)

Response (200 OK)

{
  "success": true,
  "data": {
    "overview": {
      "total_customers": 45282,
      "avg_clv": 15000.50,
      "total_clv": 679230000,
      "distribution": {
        "high": 5000,
        "medium": 20000,
        "low": 20282
      }
    },
    "top_customers": [
      {
        "customer_id": 12345,
        "email": "customer@example.com",
        "historical_value": 50000,
        "predicted_value": 75000,
        "total_orders": 25,
        "clv_tier": "high"
      }
    ]
  }
}

Churn Analysis

Analiza el riesgo de pérdida de clientes.

GET /api/v2/cdp/analytics/churn

Query Parameters

tenant_id (required): ID del tenant
risk_level (optional): active, at_risk, churning, churned

Response (200 OK)

{
  "success": true,
  "data": {
    "overview": {
      "total_customers": 29707,
      "churn_rate": 0.15,
      "at_risk_count": 4456,
      "distribution": {
        "active": 20000,
        "at_risk": 4456,
        "churning": 3000,
        "churned": 2251
      }
    },
    "at_risk_customers": [
      {
        "customer_id": 67890,
        "last_order_date": "2024-06-15",
        "days_since_last_order": 93,
        "churn_probability": 0.75,
        "churn_risk": "at_risk"
      }
    ]
  }
}

Tenant Integrations

List Integrations

Lista todas las integraciones configuradas para un tenant.

GET /api/v2/tenant-integrations/{tenantId}

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "tenant_id": 56,
      "integration_type": "vtex",
      "account_name": "chelseaio",
      "environment": "vtexcommercestable",
      "is_active": true,
      "last_sync": "2024-09-16T10:00:00Z"
    }
  ]
}

Create Integration

Crea una nueva integración para un tenant.

POST /api/v2/tenant-integrations

Request Body

{
  "tenant_id": 56,
  "integration_type": "vtex",
  "account_name": "chelseaio",
  "environment": "vtexcommercestable",
  "app_key": "vtexappkey-chelseaio-XXXXX",
  "app_token": "TOKEN_HERE"
}

Response (201 Created)

{
  "success": true,
  "message": "Integration created successfully",
  "data": {
    "id": 29,
    "tenant_id": 56,
    "integration_type": "vtex"
  }
}

Update Integration

Actualiza una integración existente.

PUT /api/v2/tenant-integrations/{integrationId}

Request Body

{
  "is_active": false,
  "app_key": "new-key",
  "app_token": "new-token"
}

Delete Integration

Elimina una integración.

DELETE /api/v2/tenant-integrations/{integrationId}

Validate VTEX Credentials

Valida credenciales VTEX antes de guardarlas.

POST /api/v2/tenant-integrations/validate/vtex

Request Body

{
  "account_name": "chelseaio",
  "app_key": "vtexappkey-chelseaio-XXXXX",
  "app_token": "TOKEN_HERE",
  "environment": "vtexcommercestable"
}

Response (200 OK)

{
  "success": true,
  "message": "VTEX credentials are valid",
  "account_info": {
    "account_name": "chelseaio",
    "is_active": true,
    "hosts": ["chelseaio.vtexcommercestable.com.br"]
  }
}

Customers

Get Customer Profile

Obtiene el perfil completo 360° de un cliente.

GET /api/v2/cdp/customers/{customerId}/profile

Parameters

customerId (path, required): ID del cliente
tenant_id (query, required): ID del tenant

Response (200 OK)

{
  "success": true,
  "data": {
    "customer": {
      "id": 12345,
      "email": "customer@example.com",
      "first_name": "Juan",
      "last_name": "Pérez",
      "created_at": "2023-01-15T10:00:00Z"
    },
    "rfm": {
      "segment": "Champion",
      "recency_days": 15,
      "frequency": 8,
      "monetary": 12500.00,
      "rfm_score": "555"
    },
    "clv": {
      "historical_value": 25000,
      "predicted_value": 35000,
      "clv_tier": "high"
    },
    "churn": {
      "risk": "active",
      "probability": 0.05
    }
  }
}

Get Customer Timeline

Obtiene el historial de actividades de un cliente.

GET /api/v2/cdp/customers/{customerId}/timeline

Parameters

customerId (path, required): ID del cliente
tenant_id (query, required): ID del tenant
limit (query, optional): Número de eventos (default: 50)

Response (200 OK)

{
  "success": true,
  "data": {
    "events": [
      {
        "type": "order",
        "timestamp": "2024-09-15T14:30:00Z",
        "details": {
          "order_id": "ORD-123456",
          "amount": 2500.00,
          "items": 3
        }
      },
      {
        "type": "email_opened",
        "timestamp": "2024-09-14T10:15:00Z",
        "details": {
          "campaign": "Back to School 2024"
        }
      }
    ]
  }
}

Events

Track Event

Registra un evento de cliente para análisis.

POST /api/v2/cdp/events

Request Body

{
  "tenant_id": 56,
  "customer_id": 12345,
  "event_type": "page_view",
  "properties": {
    "page": "/products/shoes",
    "referrer": "google.com"
  },
  "timestamp": "2024-09-16T20:00:00Z"
}

Event Types

page_view: Vista de página
add_to_cart: Producto agregado al carrito
remove_from_cart: Producto removido del carrito
purchase: Compra completada
email_opened: Email abierto
email_clicked: Click en email
campaign_converted: Conversión de campaña

Segments

List Segments

Lista todos los segmentos disponibles.

GET /api/v2/cdp/segments

Query Parameters

tenant_id (required): ID del tenant
type (optional): dynamic, static

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "VIP Customers",
      "type": "dynamic",
      "criteria": {
        "clv_tier": "high",
        "rfm_segment": ["Champions", "Loyal Customers"]
      },
      "member_count": 5000,
      "last_updated": "2024-09-16T19:00:00Z"
    }
  ]
}

Get Segment Members

Obtiene los miembros de un segmento.

GET /api/v2/cdp/segments/{segmentId}/members

Parameters

segmentId (path, required): ID del segmento
tenant_id (query, required): ID del tenant
limit (query, optional): Límite de resultados
offset (query, optional): Offset para paginación

Error Responses

Todos los endpoints pueden devolver los siguientes errores:

400 Bad Request

{
  "success": false,
  "error": "Invalid request parameters",
  "details": "tenant_id is required"
}

404 Not Found

{
  "success": false,
  "error": "Resource not found",
  "details": "Tenant with ID 999 not found"
}

500 Internal Server Error

{
  "success": false,
  "error": "Internal server error",
  "timestamp": "2024-09-16T20:00:00Z"
}

Rate Limiting

Production: 1000 requests per 15 minutes per IP
Development: 10000 requests per 15 minutes per IP

Webhooks (Coming Soon)

Próximamente se implementarán webhooks para eventos en tiempo real:

Customer profile updates
Segment changes
Campaign completions
Churn alerts

SDK Support (Coming Soon)

SDKs planificados para:

JavaScript/TypeScript
Python
PHP

Need Help?

API Status: https://nerdistan-datalake-production.up.railway.app/health
Interactive Docs: https://nerdistan-datalake-production.up.railway.app/docs
Support: Contact CDP Team

🌐 Base URLs​

Production​

Local Development​

🔐 Authentication​

📊 Endpoints Overview​

Quick Links​

CDP Processing​

Process Tenant Data​

Parameters​

Request Body​

Response (200 OK)​

Example​

Get Processing Status​

Parameters​

Response (200 OK)​

Analytics​

RFM Analysis​

Query Parameters​

Response (200 OK)​

Segments Definition​

Customer Lifetime Value (CLV)​

Query Parameters​

Response (200 OK)​

Churn Analysis​

Query Parameters​

Response (200 OK)​

Tenant Integrations​

List Integrations​

Response (200 OK)​

Create Integration​

Request Body​

Response (201 Created)​

Update Integration​

Request Body​

Delete Integration​

Validate VTEX Credentials​

Request Body​

Response (200 OK)​

Customers​

Get Customer Profile​

Parameters​

Response (200 OK)​

Get Customer Timeline​

Parameters​

Response (200 OK)​

Events​

Track Event​

Request Body​

Event Types​

Segments​

List Segments​

Query Parameters​

Response (200 OK)​

Get Segment Members​

Parameters​

Error Responses​

400 Bad Request​

404 Not Found​

500 Internal Server Error​

Rate Limiting​

Webhooks (Coming Soon)​

SDK Support (Coming Soon)​

Need Help?​

🌐 Base URLs

Production

Local Development

🔐 Authentication

📊 Endpoints Overview

Quick Links

CDP Processing

Process Tenant Data

Parameters

Request Body

Response (200 OK)

Example

Get Processing Status

Parameters

Response (200 OK)

Analytics

RFM Analysis

Query Parameters

Response (200 OK)

Segments Definition

Customer Lifetime Value (CLV)

Query Parameters

Response (200 OK)

Churn Analysis

Query Parameters

Response (200 OK)

Tenant Integrations

List Integrations

Response (200 OK)

Create Integration

Request Body

Response (201 Created)

Update Integration

Request Body

Delete Integration

Validate VTEX Credentials

Request Body

Response (200 OK)

Customers

Get Customer Profile

Parameters

Response (200 OK)

Get Customer Timeline

Parameters

Response (200 OK)

Events

Track Event

Request Body

Event Types

Segments

List Segments

Query Parameters

Response (200 OK)

Get Segment Members

Parameters

Error Responses

400 Bad Request

404 Not Found

500 Internal Server Error

Rate Limiting

Webhooks (Coming Soon)

SDK Support (Coming Soon)

Need Help?