API REST v1

Referencia completa de la API para integraciones externas con n8n, Zapier o tus propias aplicaciones.

Base URL: https://eskadia-crm.vercel.app/api/v1

Autenticación

Todas las peticiones (excepto /health) requieren un Bearer token:

Authorization: Bearer esk_live_abc123...

Genera tokens en Ajustes → API (solo admin/owner). El token se muestra una sola vez al crearlo.

Rate Limiting

TipoLímite
Lectura (GET)500 req/min
Escritura (POST/PATCH/DELETE)20 req/min
General100 req/min

Headers de respuesta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Paginación

Endpoints de listado soportan:

ParámetroDefaultMax
page1—
per_page20100
sort_bycreated_at(varía)
sort_dirdescasc/desc

Respuesta:

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

Idempotencia

Para evitar duplicados en POST, envía el header:

Idempotency-Key: unique-key-123

Si la key ya existe, se retorna la respuesta original sin re-ejecutar. Las keys expiran a las 24 horas.

Roles y permisos (RBAC)

Los tokens heredan un rol. Los permisos se aplican según la siguiente tabla:

AcciónVisorMiembroManagerAdmin
GET (listar/detalle)✓✓✓✓
POST (crear)✗✓✓✓
PATCH (actualizar)✗✓✓✓
DELETE✗✗✗✓
KPIs / Reports✗✗✓✓
Settings✗✗✗✓

Endpoints

Contacts

CRUD completo de contactos

GET/contacts
POST/contacts
GET/contacts/:id
PATCH/contacts/:id
DELETE/contacts/:id

Companies

CRUD completo de empresas

GET/companies
POST/companies
GET/companies/:id
PATCH/companies/:id
DELETE/companies/:id

Deals

CRUD completo de oportunidades

GET/deals
POST/deals
GET/deals/:id
PATCH/deals/:id
DELETE/deals/:id

Leads

CRUD completo de leads

GET/leads
POST/leads
GET/leads/:id
PATCH/leads/:id
DELETE/leads/:id

Tasks

CRUD completo de tareas

GET/tasks
POST/tasks
GET/tasks/:id
PATCH/tasks/:id
DELETE/tasks/:id

Products

Solo lectura

GET/products
GET/products/:id

Quotes

Solo lectura

GET/quotes
GET/quotes/:id

Projects

Solo lectura

GET/projects
GET/projects/:id

Activities

Listar y crear actividades

GET/activities
POST/activities
GET/activities/:id

Dashboard y Reports

KPIs y reportes (manager+)

GET/dashboard
GET/reports?type=sales|leads|activities|projects

Emails

Envío de emails (member+)

POST/emails/send

AI Proxy

Funciones de IA (member+)

POST/ai/:feature

Contracts

Contratos con firma digital

GET/contracts
POST/contracts
GET/contracts/:id
PATCH/contracts/:id
DELETE/contracts/:id

Inbox

Bandeja de entrada de email

GET/inbox/connections
GET/inbox/messages
GET/inbox/messages/:id
POST/inbox/messages/:id/reply

Support

Tickets de soporte

GET/support/tickets
POST/support/tickets
GET/support/tickets/:id
PATCH/support/tickets/:id
POST/support/tickets/:id/notes

Chat

Conversaciones del widget

GET/chat/conversations
GET/chat/conversations/:id
PATCH/chat/conversations/:id

Webinars

Gestión de webinars

GET/webinars
POST/webinars
GET/webinars/:id
GET/webinars/:id/attendees

Forms

Formularios de captura de leads

GET/forms
GET/forms/:id
GET/forms/:id/submissions

Sales Targets

Objetivos de ventas

GET/sales-targets
POST/sales-targets
PATCH/sales-targets/:id

Calendar

Conexiones de calendario

GET/calendar/connections
GET/calendar/events

Settings

Configuración (admin)

GET/settings
PATCH/settings
GET/settings/deal-stages
GET/settings/pipelines
GET/settings/webhooks
PATCH/settings/webhooks
GET/settings/modules

Formato de errores

{
  "error": {
    "code": "not_found",
    "message": "Contacto no encontrado",
    "doc_url": "https://docs.eskadia.com/api/errors#not_found"
  }
}

Códigos: invalid_request, authentication_required, insufficient_permissions, not_found, rate_limit_exceeded, validation_error, idempotency_conflict, internal_error

Metadata

Contacts, deals, quotes y leads soportan un campo metadata (JSON libre):

# Crear con metadata
POST /contacts
{ "first_name": "Ana", "metadata": { "source": "api" } }

# Actualizar (merge, no reemplaza)
PATCH /contacts/:id
{ "metadata": { "new_field": "value" } }

Ejemplos

Health check

curl https://eskadia-crm.vercel.app/api/v1/health

Listar contactos

curl -H "Authorization: Bearer esk_live_..." \
  "https://eskadia-crm.vercel.app/api/v1/contacts?page=1&per_page=10&search=juan"

Crear contacto con idempotencia

curl -X POST \
  -H "Authorization: Bearer esk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-123" \
  -d '{"first_name":"Juan","last_name":"Garcia","email":"juan@example.com"}' \
  https://eskadia-crm.vercel.app/api/v1/contacts

Dashboard KPIs

curl -H "Authorization: Bearer esk_live_..." \
  https://eskadia-crm.vercel.app/api/v1/dashboard

¿Primera vez con Eskadia?

Consulta la guía completa de funcionalidades para aprender a usar el CRM.

Ver documentación