Aller au contenu principal

OmniCRM API

Toutes les fonctions d'OmniCRM sont accessibles via l'API - Il n'y a pas de fonctionnalité qui est uniquement disponible dans l'interface utilisateur.

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 à l'aide de plusieurs méthodes d'authentification, y compris les jetons JWT, les clés API et le blanchiment d'adresses IP.

L'API est documentée à l'aide de Swagger, un outil qui permet une lecture, une compréhension et un test faciles de la fonctionnalité de l'API.

La documentation de l'API est disponible à l'URL suivante :

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

OmniCRM Swagger Page

Méthodes d'Authentification​

OmniCRM prend en charge trois méthodes d'authentification, chacune conçue pour différents cas d'utilisation :

  1. Jetons JWT Bearer - Pour les sessions utilisateur interactives (UI Web, applications mobiles)
  2. Clés API - Pour les intégrations serveur à serveur et les scripts d'automatisation
  3. Blanchiment d'IP - Pour les systèmes internes de confiance (serveurs de provisionnement, outils de surveillance)

Authentification par Jeton JWT Bearer​

C'est la méthode d'authentification principale pour les sessions utilisateur. Les utilisateurs se connectent avec leur e-mail et leur mot de passe, reçoivent un jeton JWT et l'utilisent pour les requêtes suivantes.

Cas d'utilisation :

  • Authentification de l'interface Web
  • Authentification des applications mobiles
  • 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 jeton lorsqu'il expire, ainsi que les autorisations 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.

OmniCRM Swagger Page

Pour autoriser la session, copiez la valeur du jeton et cliquez sur le bouton "Authorize" en haut à droite de la page Swagger. Collez le jeton dans le champ "Value", préfixé par Bearer et cliquez sur "Authorize".

OmniCRM Swagger Bearer Auth

Maintenant, toutes les requêtes suivantes seront authentifiées avec ce jeton.

Authentification par Clé API​

Les clés API fournissent une authentification sécurisée et de longue durée 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 travaux cron

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 passée 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 un accès 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 les clients
response = requests.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
    print(customer)

Meilleures Pratiques :

  • Générer des clés API à l'aide de générateurs aléatoires cryptographiquement sécurisés (openssl rand -base64 48)
  • Utiliser différentes clés API pour différents systèmes
  • Documenter l'objectif de chaque clé API dans le champ description
  • Faire tourner les clés API périodiquement
  • Ne jamais commettre les clés API dans le contrôle de version
  • Attribuer les permissions minimales nécessaires à chaque clé API

Authentification par Blanchiment d'IP​

Le blanchiment d'IP permet à des adresses IP spécifiques d'accéder à l'API sans authentification. Cela est utile pour des 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 VLAN de gestion
  • Playbooks Ansible s'exécutant sur une infrastructure contrôlée

Configuration de la Liste Blanche 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é :

  • Utiliser le blanchiment d'IP uniquement sur des réseaux privés et sécurisés
  • Ne jamais blanchir des adresses IP publiques
  • Utiliser les plages d'IP les plus spécifiques possibles
  • Documenter pourquoi chaque IP est blanchie
  • Auditer régulièrement les IP blanchies

Exemples d'Appels API avec Python​

Voici un exemple de la façon de se connecter et de récupérer une liste de clients en utilisant l'authentification par jeton JWT :

import requests

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

print("Provisionnement des données au serveur : " + str(crm_url))

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

# Obtenir le jeton d'authentification
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 les clients
response = session.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
    print(customer)