⚡ XALVEN ELITE — API pública

Versión v1 · base URL https://elite.xalven.app/api/v1
Índice

Autenticación

Todas las peticiones requieren un header Authorization: Bearer <api_key>. Genera y gestiona tus API keys desde /elite/api-keys (solo el admin del account).

Las keys tienen el formato xve_live_ seguido de 32 caracteres hex. Se muestran una sola vez al crearlas; guárdalas en un gestor de secretos.

curl -H "Authorization: Bearer xve_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://elite.xalven.app/api/v1/campaigns

Rate limit

100 requests por minuto por API key, ventana deslizante. Si lo excedes recibes 429 Too Many Requests con header Retry-After y body:

{
  "error": "rate_limit_exceeded",
  "message": "Has superado el límite de 100 requests por minuto. Espera antes de reintentar.",
  "retry_after_seconds": 42
}

Códigos de error

CódigoSignificado
401Authorization Bearer ausente, key inválida, revocada o expirada.
403La key es válida pero la operación no está permitida (ej. transición prohibida).
404Recurso no encontrado o no pertenece al account de la key.
429Rate limit excedido. Mira el header Retry-After.
500Error interno. Si persiste, contáctanos.

Campañas

GET/api/v1/campaigns

Lista las campañas del account.

Query params

statusopcional · draft, active, paused, completed, cancelled
pageopcional · default 1
per_pageopcional · default 20, máx 100

Response

{
  "campaigns": [
    {
      "id": "ab12...",
      "workspace_id": "ws_xxx",
      "name": "Outbound Q2 dental",
      "status": "active",
      "data_source": "directorio",
      "daily_limit": 50,
      "sequence_max_emails": 3,
      "approval_mode": "supervised",
      "created_at": "2026-04-12T10:00:00",
      "started_at": "2026-04-15T08:00:00",
      "paused_at": null,
      "completed_at": null
    }
  ],
  "total": 7,
  "page": 1,
  "per_page": 20
}
GET/api/v1/campaigns/{id}

Detalle de campaña con métricas agregadas.

Response

{
  "id": "ab12...",
  "workspace_id": "ws_xxx",
  "name": "Outbound Q2 dental",
  "status": "active",
  "metrics": { "sent": 412, "opened": 173, "replied": 29, "leads": 8 }
}
POST/api/v1/campaigns/{id}/pause

Pausa la campaña. 409 si está en estado terminal (completed o cancelled).

POST/api/v1/campaigns/{id}/resume

Reanuda la campaña (status active). Valida cupo del plan (max_campaigns_active).

Prospectos

GET/api/v1/prospects

Lista los prospectos del account.

Query params

campaign_idopcional · filtra por campaña
statusopcional · contacted, replied, qualified_hot, qualified_warm, qualified_cold, meeting_scheduled, blacklisted… (lista completa en el código)
qualificationopcional · atajo para status: hot | warm | cold
page / per_pagepaginación (default 20, máx 100)

Response

{
  "prospects": [
    {
      "id": "pr_...",
      "campaign_id": "ab12...",
      "business_name": "Clínica Dental Madrid",
      "email": "info@ejemplo.com",
      "city": "Madrid",
      "status": "qualified_warm",
      "lead_score": 82.5,
      "total_opens": 4,
      "total_clicks": 1,
      "first_reply_at": "2026-04-22T11:30:12"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}
GET/api/v1/prospects/{id}

Detalle del prospecto + timeline (emails enviados + respuestas recibidas).

{
  "prospect": { "id": "pr_...", "business_name": "...", "status": "replied" },
  "timeline": {
    "emails":    [ { "id": "em_1", "sequence_number": 1, "subject": "...", "sent_at": "...", "opens": 3 } ],
    "responses": [ { "id": "rs_1", "from_email": "...", "qualification_status": "warm" } ]
  }
}
POST/api/v1/prospects/{id}/blacklist

Marca el prospecto como blacklisted y añade su email/dominio a la lista negra del account. Honra la LEY Nº2: nunca se volverá a contactar.

POST/api/v1/prospects/{id}/recontact

Genera un nuevo email para un prospect ya contactado, ignorando la deduplicación del workspace. Es un override explícito de la LEY Nº2: quien lo dispara asume el riesgo de saturar al destinatario.

Devuelve 409 si el prospect está en blacklisted, bounced o unsubscribed.

Métricas

GET/api/v1/metrics

Métricas agregadas del account, opcionalmente filtradas.

Query params

campaign_idopcional · limita a una campaña
from_dateopcional · YYYY-MM-DD inclusive
to_dateopcional · YYYY-MM-DD inclusive

Response

{
  "filters": { "campaign_id": null, "from_date": "2026-04-01", "to_date": null },
  "sent": 1820,
  "opened": 612,
  "replied": 84,
  "leads": 19,
  "open_rate": 0.3363,
  "reply_rate": 0.0462
}

sent: emails con status sent o delivered. opened / replied: prospectos únicos. leads: prospectos en estado cualificado o convertido.

Workspaces

GET/api/v1/workspaces

Lista los workspaces del account (excluye los archivados).

{
  "workspaces": [
    {
      "id": "ws_...",
      "name": "ARXYA",
      "mode": "email_only",
      "status": "active",
      "sender_name": "Luis Rodríguez",
      "sender_email": "hola@arxya.app",
      "tone": "profesional_cercano"
    }
  ],
  "total": 1
}