Dans un paysage de plus en plus numérique, les organisations à but non lucratif et les associations ont besoin de solutions fluides pour gérer leurs données d’adhésion entre différentes plateformes. HelloAsso, plateforme française très utilisée pour la collecte de dons et la gestion des membres, propose des outils puissants pour gérer les dons, les événements et les adhésions. D’un autre côté, Dolibarr ERP & CRM est un logiciel libre et flexible qui permet aux associations de gérer leurs finances, leur CRM et leurs membres dans un environnement unifié. Synchroniser HelloAsso avec Dolibarr est une étape précieuse pour les structures souhaitant automatiser leurs flux de données et gagner en efficacité.

Dans ce guide détaillé, nous vous montrons comment automatiser la synchronisation des membres HelloAsso avec Dolibarr à l’aide des pipelines CI/CD de GitLab. Nous abordons l’accès aux API, la transformation des données, le mappage vers les structures Dolibarr, la configuration CI, ainsi que les bonnes pratiques pour une synchronisation robuste et évolutive.

1. Présentation de la gestion des membres sur HelloAsso et Dolibarr

HelloAsso permet aux organisations de collecter des données via des formulaires liés aux adhésions, aux dons et aux événements. Ces formulaires génèrent des ensembles de données contenant des informations telles que le nom, l’email, le téléphone et le statut d’adhésion.

Dolibarr, via ses modules "Adhérents" et "Tiers", permet de gérer les profils des membres, les dates de cotisation, les types d’adhésion, etc. La synchronisation des deux plateformes permet de maintenir une source unique de vérité et de réduire les mises à jour manuelles.

2. Pourquoi automatiser avec GitLab CI ?

GitLab CI (Intégration Continue) offre un moyen puissant d’automatiser les tâches récurrentes de synchronisation. Ses atouts :

• Exécution planifiée des tâches (via syntaxe cron)

• Stockage sécurisé des identifiants via les variables CI/CD

• Pipelines réutilisables pour différents projets

• Intégration avec les API REST et scripts Python

Grâce à GitLab CI, les données HelloAsso sont régulièrement récupérées, transformées, puis insérées dans Dolibarr sans intervention humaine.

3. Prérequis nécessaires

Avant de commencer, assurez-vous de disposer de :

• Un compte HelloAsso avec accès à l’API (identifiants OAuth2)

• Une instance Dolibarr avec le module "Adhérents" activé

• Un accès administrateur à GitLab et un dépôt Git pour gérer les jobs

• Python 3 installé localement pour le développement des scripts

4. Obtenir l’accès à l’API HelloAsso

Pour accéder aux données HelloAsso :

• Enregistrez votre application via le portail développeur de HelloAsso

• Obtenez un client_id et un client_secret

• Utilisez OAuth2 pour générer un token d’accès

Exemple de script Python pour récupérer un token :

import requests

response = requests.post("https://api.helloasso.com/oauth2/token", data={
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "scope": "api"})

token = response.json()["access_token"]

5. Récupérer les données d’adhérents depuis HelloAsso

Une fois le token obtenu, utilisez l’endpoint suivant pour extraire les membres :

GET https://api.helloasso.com/v3/organizations/{organizationSlug}/forms/{formType}/{formSlug}/items

Paginer les résultats et filtrer par date permet de limiter la charge.

6. Comprendre l’API Dolibarr

L’API REST de Dolibarr permet les opérations CRUD sur de nombreux modules. Pour les adhérents :

• POST /members pour créer un membre

• GET /members pour récupérer les membres existants

• PUT /members/{id} pour mettre à jour un membre

Chaque requête nécessite une clé API, générée depuis le back-office de Dolibarr. Cette clé doit être stockée de façon sécurisée dans les variables GitLab CI/CD.

7. Mappage des champs HelloAsso vers Dolibarr

Le principal défi est de faire correspondre les champs des deux plateformes. Exemples :

Un script de transformation est nécessaire pour cette étape.

8. Écrire le script Python de synchronisation

Ce script doit :

• S’authentifier auprès des deux APIs

• Récupérer les adhérents depuis HelloAsso

• Vérifier si le membre existe déjà dans Dolibarr

• Créer ou mettre à jour le membre selon le cas

Bonnes pratiques :

• Journaliser les erreurs et succès

• Générer un rapport de synchronisation

• Garantir l’idempotence pour éviter les doublons

9. Configuration CI/CD dans GitLab

Exemple minimal de fichier .gitlab-ci.yml :

stages:
  - sync

variables:
  DOLIBARR_API_KEY: $DOLIBARR_API_KEY
  HELLOASSO_CLIENT_ID: $HELLOASSO_CLIENT_ID
  HELLOASSO_CLIENT_SECRET: $HELLOASSO_CLIENT_SECRET

sync_members:
  stage: sync
  image: python:3.10
  script:
    - pip install -r requirements.txt
    - python sync_members.py
  only:
    - schedules

Les variables d’environnement doivent être déclarées dans GitLab (CI/CD > Variables).

10. Planification du pipeline

GitLab permet de planifier les exécutions :

• Allez dans CI/CD > Schedules

• Créez une planification (ex : 0 6 * * * pour chaque jour à 6h)

• Associez-la au job sync_members

Cela garantit une synchronisation quotidienne entre HelloAsso et Dolibarr.

11. Gérer les doublons et les mises à jour

Pour éviter les doublons :

• Rechercher les membres existants via l’email ou un identifiant unique

• Comparer les champs avant d’effectuer une mise à jour

• Utiliser PUT uniquement si les données ont changé

Si l’API des adhérents est limitée, le module "Tiers" peut stocker des informations supplémentaires.

12. Logs et notifications

Pour une bonne observabilité :

• Générer des fichiers de logs horodatés

• Stocker les rapports comme artefacts GitLab

• Facultativement, envoyer des emails via SMTP

13. Sécurité des données et conformité

Respectez le RGPD :

• Ne stockez que les données nécessaires

• Chiffrez les variables CI/CD

• Ne journalisez pas les données sensibles

14. Monter en charge

Pour des volumes plus importants :

• Implémentez un cache des appels API

• Utilisez le traitement par lots

• Filtrez les données modifiées plutôt qu’un full sync

15. Améliorations futures

Des évolutions possibles :

• Ajouter des tests unitaires

• Étendre aux dons, événements, etc.

• Développer un tableau de bord de supervision

16. Conclusion

Synchroniser les membres HelloAsso avec Dolibarr via GitLab CI permet une gestion automatisée, fiable et évolutive. Grâce aux APIs et à l’automatisation CI/CD, les associations peuvent réduire les interventions humaines, améliorer la qualité des données et moderniser leur back-office. Ce système devient ainsi une colonne vertébrale robuste pour l’administration numérique des associations.