OmniCRM API

Todas las funciones dentro de OmniCRM son accesibles a través de la API - No hay funcionalidad que esté disponible solo en la interfaz de usuario.

Esto te permite integrar OmniCRM con otros sistemas o automatizar tareas.

La API es una API RESTful y está asegurada utilizando múltiples métodos de autenticación, incluyendo tokens JWT, claves API y listas blancas de IP.

La documentación de la API está documentada utilizando Swagger, una herramienta que permite una fácil lectura, comprensión y prueba de la funcionalidad de la API.

La documentación de la API está disponible en la siguiente URL:

<https://yourcrm/crm/docs/>

Métodos de Autenticación

OmniCRM soporta tres métodos de autenticación, cada uno diseñado para diferentes casos de uso:

1. Tokens Bearer JWT - Para sesiones de usuario interactivas (UI web, aplicaciones móviles)
2. Claves API - Para integraciones de servidor a servidor y scripts de automatización
3. Lista Blanca de IP - Para sistemas internos de confianza (servidores de aprovisionamiento, herramientas de monitoreo)

Autenticación con Token Bearer JWT

Este es el método de autenticación principal para las sesiones de usuario. Los usuarios inician sesión con correo electrónico y contraseña, reciben un token JWT y lo utilizan para solicitudes posteriores.

Casos de Uso:

• Autenticación de UI web
• Autenticación de aplicaciones móviles
• Acceso programático de corta duración

Cómo Autenticarse:

Para iniciar sesión, envía un cuerpo JSON con la siguiente estructura a /crm/auth/login como una solicitud POST:

{
    "email": "youruser@yourdomain.com",
    "password": "yourpassword"
}

La API devolverá un objeto JSON que contiene un campo token, que se utiliza para autenticar todas las solicitudes futuras. Además, la respuesta incluye un refresh_token que se puede usar para refrescar el token cuando expire, junto con los permisos y roles del usuario.

Puedes probar esto desde la página de Swagger seleccionando el endpoint /auth/login, completando tu Nombre de Usuario y Contraseña, y haciendo clic en el botón Try it out.

Para autorizar la sesión, copia el valor del token y haz clic en el botón "Authorize" en la parte superior derecha de la página de Swagger. Pega el token en el campo "Value", precedido por Bearer y haz clic en "Authorize".

Ahora, todas las solicitudes posteriores estarán autenticadas con este token.

Autenticación con Clave API

Las claves API proporcionan autenticación segura y de larga duración para integraciones de servidor a servidor y scripts de automatización sin requerir contraseñas de usuario.

Casos de Uso:

• Sistemas de aprovisionamiento automatizados
• Herramientas de monitoreo y alerta
• Integración con sistemas externos
• Tareas programadas y trabajos cron

Cómo Funcionan las Claves API:

Las claves API se configuran en el archivo crm_config.yaml y están asociadas con roles y permisos específicos. Cada clave API es una cadena aleatoria segura (mínimo 32 caracteres) que autentica las solicitudes cuando se pasa en el encabezado X-API-KEY.

Configurando Claves API:

Las claves API deben ser añadidas al crm_config.yaml por un administrador con acceso al servidor:

api_keys:
  your-secure-api-key-here-minimum-32-chars:
    roles:
      - admin
    description: "Sistema de automatización de aprovisionamiento"
  another-api-key-for-monitoring-system:
    roles:
      - view_customer
      - view_service
    description: "Monitoreo y alerta"

Usando Claves API:

Incluye la clave API en el encabezado X-API-KEY de tus solicitudes:

curl -X GET "https://yourcrm.com/crm/customers" \
  -H "X-API-KEY: your-secure-api-key-here-minimum-32-chars"

Ejemplo en Python:

import requests

crm_url = 'https://yourcrm.com'
api_key = 'your-secure-api-key-here-minimum-32-chars'

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": api_key
}

# Obtener Clientes
response = requests.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
    print(customer)

Mejores Prácticas:

• Genera claves API utilizando generadores aleatorios seguros criptográficamente (openssl rand -base64 48)
• Usa diferentes claves API para diferentes sistemas
• Documenta el propósito de cada clave API en el campo description
• Rota las claves API periódicamente
• Nunca cometas claves API en el control de versiones
• Asigna los permisos mínimos necesarios a cada clave API

Autenticación con Lista Blanca de IP

La lista blanca de IP permite que direcciones IP específicas accedan a la API sin autenticación. Esto es útil para sistemas internos de confianza en redes privadas.

Casos de Uso:

• Servidores de aprovisionamiento internos
• Sistemas de monitoreo de red en VLANs de gestión
• Playbooks de Ansible ejecutándose en infraestructura controlada

Configurando la Lista Blanca de IP:

Agrega direcciones IP de confianza a crm_config.yaml:

ip_whitelist:
  - 192.168.1.100
  - 10.0.0.0/24
  - 172.16.50.10

Consideraciones de Seguridad:

• Usa la lista blanca de IP solo en redes privadas y seguras
• Nunca incluyas direcciones IP públicas en la lista blanca
• Usa los rangos de IP más específicos posibles
• Documenta por qué cada IP está en la lista blanca
• Audita regularmente las IPs en la lista blanca

Ejemplo de Llamadas a la API con Python

Aquí hay un ejemplo de cómo iniciar sesión y recuperar una lista de clientes utilizando autenticación con token JWT:

import requests

crm_url = 'https://yourcrm.com'
session = requests.Session()

print("Aprovisionando datos al servidor: " + str(crm_url))

headers = {
    "Content-Type": "application/json"
}

# Obtener Token de Autenticación
response = session.post(crm_url + '/crm/auth/login', json={
    "email": "youruser@yourdomain.com",
    "password": "yourpassword"
}, headers=headers)

print(response.status_code)
print(response.json())
assert response.status_code == 200

headers['Authorization'] = 'Bearer ' + response.json()['token']
print("Autenticado en CRM exitosamente")

# Obtener Clientes
response = session.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
    print(customer)