Autenticación

La API pública de Zelta CRM se autentica mediante API Keys que se envían en el header Authorization de cada solicitud.

¿Cómo funciona?

Todas las solicitudes a la API pública deben incluir el header de autenticación con el esquema Bearer:

Authorization: Bearer zk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La API valida la clave en cada solicitud. Si la clave es inválida, está expirada, fue revocada o no se incluye, la API retorna un error de autenticación.

Prefijo de las claves

Todas las API Keys de Zelta CRM comienzan con el prefijo zk_. Esto te permite identificarlas fácilmente y distinguirlas de otras credenciales en tu sistema.

Obtener una API Key

1. Inicia sesión en tu espacio de trabajo de Zelta CRM.
2. Navega a Configuración → API Keys en el menú lateral.
3. Haz clic en Crear API Key.
4. Ingresa un nombre descriptivo para la clave (por ejemplo, Integración ERP, Bot de sincronización).
5. Selecciona los permisos que necesita la clave.
6. Opcionalmente, define una fecha de expiración.
7. Haz clic en Crear y copia la clave generada.

La clave solo se muestra una vez

Por seguridad, el valor completo de la API Key solo se muestra en el momento de creación. Una vez que cierras el diálogo, no podrás verla de nuevo. Cópiala y guárdala en un lugar seguro antes de continuar. En el servidor solo se almacena un hash SHA-256 de la clave.

Permisos

Cada API Key tiene asociado un conjunto de permisos que determinan qué operaciones puede realizar. Los permisos siguen el formato recurso:acción.

Permisos disponibles

Recurso	Permiso	Descripción
Contactos	contacts:read	Listar y consultar contactos
Contactos	contacts:create	Crear nuevos contactos
Contactos	contacts:update	Actualizar contactos existentes
Contactos	contacts:delete	Eliminar contactos
Empresas	companies:read	Listar y consultar empresas
Empresas	companies:create	Crear nuevas empresas
Empresas	companies:update	Actualizar empresas existentes
Empresas	companies:delete	Eliminar empresas
Negocios	deals:read	Listar y consultar negocios
Negocios	deals:create	Crear nuevos negocios
Negocios	deals:update	Actualizar negocios existentes
Negocios	deals:delete	Eliminar negocios
Actividades	activities:read	Listar y consultar actividades
Actividades	activities:create	Crear nuevas actividades
Actividades	activities:update	Actualizar actividades existentes
Actividades	activities:delete	Eliminar actividades
Productos	products:read	Listar y consultar productos
Productos	products:create	Crear nuevos productos
Productos	products:update	Actualizar productos existentes
Productos	products:delete	Eliminar productos

Comodines de permisos

Patrón	Descripción
*	Acceso completo a todos los recursos y acciones
contacts:*	Acceso completo al recurso de contactos
deals:*	Acceso completo al recurso de negocios

Principio de mínimo privilegio

Crea claves con solo los permisos que tu integración realmente necesita. Una clave de lectura para un sistema de reportes no necesita permisos de escritura ni eliminación.

Uso de la API Key

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

Ejemplo JS

const response = await fetch('https://api-crm.zelta.dev/public/v1/contacts', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.ZELTA_API_KEY}`
  }
});

const result = await response.json();

Ejemplo Py

import requests

response = requests.get(
    'https://api-crm.zelta.dev/public/v1/contacts',
    headers={
        'Authorization': f"Bearer {os.environ['ZELTA_API_KEY']}"
    }
)

result = response.json()

URLs base

Entorno	URL
Producción	https://api-crm.zelta.dev/public/v1
Desarrollo	https://dev-api-crm.zelta.dev/public/v1

Errores de autenticación

HTTP	Código de error	Descripción
401	INVALID_API_KEY	La clave no existe o el formato es incorrecto
401	API_KEY_EXPIRED	La clave superó su fecha de expiración
401	API_KEY_REVOKED	La clave fue revocada manualmente
403	API_KEY_FORBIDDEN	La clave no tiene permiso para esta operación
423	TENANT_SUSPENDED	El espacio de trabajo está suspendido

Ejemplo de respuesta de error:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key inválida o no encontrada"
  }
}

Buenas prácticas de seguridad

• Usa variables de entorno — nunca escribas la clave directamente en el código fuente ni en repositorios
• Rota las claves periódicamente — no esperes a que expiren; reemplázalas de forma proactiva
• Una clave por integración — crea claves independientes para cada sistema o servicio que se conecte al CRM
• Asigna solo los permisos necesarios — una integración de lectura no necesita permisos de escritura
• Monitorea el uso — revisa las claves activas desde Configuración → API Keys para detectar accesos inesperados

# Ejemplo: almacena la clave en una variable de entorno
export ZELTA_API_KEY="zk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

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

Siguientes pasos

• — URL base, límites de uso, formato de respuestas y códigos de error
• — Listar, crear y gestionar contactos por API
• — Listar, crear y gestionar empresas por API