Autenticacion

La API de Zelta CRM utiliza autenticacion basada en tokens Bearer (OAuth 2.0) para proteger el acceso a los recursos.

URL base

https://api.zelta.dev/crm/v1

Obtener un token de acceso

Paso 1: Crear una aplicacion API

1. Ve a Ajustes > API > Aplicaciones.
2. Haz clic en + Nueva aplicacion.
3. Completa los datos:
   • Nombre de la aplicacion
   • URL de redireccion (para flujo OAuth)
   • Scopes requeridos
4. Guarda y copia tu client_id y client_secret.

Seguridad

El client_secret solo se muestra una vez al momento de crearlo. Guardalo en un lugar seguro. Si lo pierdes, deberas generar uno nuevo.

Paso 2: Solicitar un token

Realiza una peticion POST al endpoint de autenticacion:

curl -X POST https://api.zelta.dev/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "tu_client_id",
    "client_secret": "tu_client_secret",
    "scope": "crm:read crm:write"
  }'

Respuesta exitosa

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_a1b2c3d4e5f6...",
  "scope": "crm:read crm:write"
}

Paso 3: Usar el token

Incluye el token en el header Authorization de cada peticion:

curl -X GET https://api.zelta.dev/crm/v1/contacts \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Scopes disponibles

Los scopes controlan que operaciones puede realizar tu aplicacion:

Scope	Descripcion	Permisos
crm:read	Lectura de datos del CRM	Consultar contactos, negocios, actividades y pipelines
crm:write	Escritura de datos del CRM	Crear y actualizar contactos, negocios y actividades
crm:delete	Eliminacion de registros	Eliminar contactos, negocios y actividades
crm:automations	Gestion de automatizaciones	Crear, editar y ejecutar automatizaciones y secuencias
crm:reports	Acceso a reportes	Consultar dashboards, pronosticos y metricas
crm:admin	Administracion completa	Todos los permisos, gestion de usuarios y configuracion

Principio de minimo privilegio

Solicita unicamente los scopes que tu aplicacion necesita. Por ejemplo, si solo necesitas leer contactos, usa crm:read en lugar de crm:admin.

Renovacion de tokens

Los tokens tienen una vigencia de 1 hora (3600 segundos). Para renovar:

curl -X POST https://api.zelta.dev/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "rt_a1b2c3d4e5f6...",
    "client_id": "tu_client_id"
  }'

Respuesta de renovacion

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_nuevo_token...",
  "scope": "crm:read crm:write"
}

Renovacion proactiva

Implementa la renovacion del token antes de que expire (por ejemplo, a los 50 minutos) para evitar interrupciones en tus integraciones.

Errores de autenticacion

Codigo HTTP	Error	Descripcion
401	unauthorized	Token ausente, expirado o invalido
403	forbidden	El token no tiene los scopes necesarios para esta operacion
429	rate_limited	Se excedio el limite de peticiones

Ejemplo de error

{
  "error": "unauthorized",
  "message": "El token de acceso ha expirado.",
  "hint": "Solicita un nuevo token usando tu refresh_token."
}

Limites de tasa (Rate Limiting)

Plan	Limite por minuto
Free	30 peticiones
Starter	100 peticiones
Professional	500 peticiones
Business	2,000 peticiones

Los headers de respuesta incluyen informacion sobre tu limite actual:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1709145600

Header	Descripcion
X-RateLimit-Limit	Maximo de peticiones permitidas en la ventana actual
X-RateLimit-Remaining	Peticiones restantes en la ventana actual
X-RateLimit-Reset	Timestamp Unix de cuando se reinicia el contador

Manejo de errores 429

Implementa un mecanismo de reintento exponencial (exponential backoff) para manejar errores 429 de manera elegante. Ejemplo: esperar 1s, 2s, 4s, 8s entre reintentos.