OmniCRM API
Toutes les fonctions d'OmniCRM sont accessibles via l'API - Il n'y a pas de fonctionnalité uniquement disponible dans l'UI.
Cela vous permet d'intégrer OmniCRM avec d'autres systèmes ou d'automatiser des tâches.
L'API est une API RESTful, et est sécurisée en utilisant plusieurs méthodes d'authentification, y compris les tokens JWT, les clés API et le whitelistage d'IP.
L'API est documentée à l'aide de Swagger, un outil qui permet une lecture, une compréhension et un test faciles des fonctionnalités de l'API.
La documentation de l'API est disponible à l'URL suivante :
Méthodes d'authentification
OmniCRM prend en charge trois méthodes d'authentification, chacune conçue pour différents cas d'utilisation :
- Tokens JWT Bearer - Pour les sessions utilisateur interactives (Web UI, applications mobiles)
- Clés API - Pour les intégrations serveur à serveur et les scripts d'automatisation
- Whitelist d'IP - Pour les systèmes internes de confiance (serveurs de provisionnement, outils de surveillance)
Authentification par Token JWT Bearer
C'est la méthode d'authentification principale pour les sessions utilisateur. Les utilisateurs se connectent avec leur email et mot de passe, reçoivent un token JWT et l'utilisent pour les requêtes suivantes.
Cas d'utilisation :
- Authentification Web UI
- Authentification d'application mobile
- Accès programmatique à court terme
Comment s'authentifier :
Pour se connecter, envoyez un corps JSON avec la structure suivante à /crm/auth/login en tant que requête POST :
{
"email": "youruser@yourdomain.com",
"password": "yourpassword"
}
L'API renverra un objet JSON contenant un champ token, qui est utilisé pour authentifier toutes les requêtes futures. De plus, la réponse inclut un refresh_token qui peut être utilisé pour rafraîchir le token lorsqu'il expire, ainsi que les permissions et rôles de l'utilisateur.
Vous pouvez tester cela depuis la page Swagger en sélectionnant le point de terminaison /auth/login, en remplissant votre nom d'utilisateur et votre mot de passe, puis en cliquant sur le bouton Try it out.
Pour autoriser la session, copiez la valeur du token et cliquez sur le bouton "Authorize" en haut à droite de la page Swagger. Collez le token dans le champ "Value", préfixé par Bearer et cliquez sur "Authorize".
Maintenant, toutes les requêtes suivantes seront authentifiées avec ce token.
Authentification par Clé API
Les clés API fournissent une authentification sécurisée et à long terme pour les intégrations serveur à serveur et les scripts d'automatisation sans nécessiter de mots de passe utilisateur.
Cas d'utilisation :
- Systèmes de provisionnement automatisés
- Outils de surveillance et d'alerte
- Intégration avec des systèmes externes
- Tâches planifiées et cron jobs
Comment fonctionnent les Clés API :
Les clés API sont configurées dans le fichier crm_config.yaml et sont associées à des rôles et permissions spécifiques. Chaque clé API est une chaîne aléatoire sécurisée (minimum 32 caractères) qui authentifie les requêtes lorsqu'elle est transmise dans l'en-tête X-API-KEY.
Configuration des Clés API :
Les clés API doivent être ajoutées à crm_config.yaml par un administrateur ayant accès au serveur :
api_keys:
your-secure-api-key-here-minimum-32-chars:
roles:
- admin
description: "Syst��me d'automatisation de provisionnement"
another-api-key-for-monitoring-system:
roles:
- view_customer
- view_service
description: "Surveillance et alerte"
Utilisation des Clés API :
Incluez la clé API dans l'en-tête X-API-KEY de vos requêtes :
curl -X GET "https://yourcrm.com/crm/customers" \
-H "X-API-KEY: your-secure-api-key-here-minimum-32-chars"
Exemple 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
}
# Obtenir des Clients
response = requests.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
print(customer)
Meilleures pratiques :
- Générez des clés API à l'aide de générateurs aléatoires sécurisés sur le plan cryptographique (
openssl rand -base64 48) - Utilisez des clés API différentes pour différents systèmes
- Documentez l'objectif de chaque clé API dans le champ
description - Faites tourner les clés API périodiquement
- Ne jamais commettre les clés API dans le contrôle de version
- Attribuez les permissions minimales nécessaires à chaque clé API
Authentification par Whitelist d'IP
Le whitelistage d'IP permet à des adresses IP spécifiques d'accéder à l'API sans authentification. Cela est utile pour les systèmes internes de confiance sur des réseaux privés.
Cas d'utilisation :
- Serveurs de provisionnement internes
- Systèmes de surveillance réseau sur des VLANs de gestion
- Playbooks Ansible exécutés sur une infrastructure contrôlée
Configuration de la Whitelist d'IP :
Ajoutez des adresses IP de confiance à crm_config.yaml :
ip_whitelist:
- 192.168.1.100
- 10.0.0.0/24
- 172.16.50.10
Considérations de sécurité :
- N'utilisez le whitelistage d'IP que sur des réseaux privés et sécurisés
- Ne jamais whitelist des adresses IP publiques
- Utilisez les plages d'IP les plus spécifiques possibles
- Documentez pourquoi chaque IP est whitelistée
- Auditez régulièrement les IP whitelistées
Exemples d'appels API avec Python
Voici un exemple de comment se connecter et récupérer une liste de clients en utilisant l'authentification par token JWT :
import requests
crm_url = 'https://yourcrm.com'
session = requests.Session()
print("Provisioning data to server: " + str(crm_url))
headers = {
"Content-Type": "application/json"
}
# Obtenir le Token d'Auth
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("Authentifié avec succès au CRM")
# Obtenir des Clients
response = session.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
print(customer)