Changer de plateforme de dons est facile à justifier et douloureux à exécuter. Votre liste de donateurs, l'historique de vos campagnes et des années d'enregistrements de dons se trouvent dans Donorbox – et passer à une nouvelle plateforme signifiait traditionnellement l'une des deux choses suivantes : recommencer à zéro et perdre votre historique, ou passer des jours à manipuler manuellement des feuilles de calcul.

L'importateur Donorbox pour Charitable Pro élimine ce compromis.

Il lit les mêmes fichiers CSV que Donorbox vous permet déjà d'exporter, les fait correspondre au modèle de données de Charitable, et vous guide tout au long de la migration dans un assistant guidé en six étapes. Les donateurs, les campagnes, l'historique des dons et les enregistrements des plans récurrents arrivent intacts dans Charitable – prêts à alimenter vos e-mails de remerciement, vos campagnes de réengagement et vos rapports à long terme.

Un mode d'essai intégré vous permet de prévisualiser exactement ce qui sera importé avant qu'un seul enregistrement ne soit écrit. Et si quelque chose semble erroné après votre engagement, une annulation en un clic supprime tout ce que l'importation a créé, laissant votre base de données exactement comme elle était.

Disponible dans Charitable Pro 1.8.14 et versions ultérieures.

Voici un aperçu de l'outil :

Ce que contient ce guide ?

Ce que vous obtenez avec l'importateur Donorbox

Voici ce qui est inclus dans cette fonctionnalité :

• Assistant en six étapes : téléchargement, prévisualisation, options, importation, résultats et annulation facultative.
• Importe les donateurs, les campagnes, les dons et les plans récurrents (archivage uniquement) à partir des exportations CSV standard de Donorbox.
• Détecte automatiquement les colonnes CSV à partir d'une liste blanche de schéma stable avec plusieurs alias d'en-tête par champ.
• Le mode d'essai prévisualise tout sans écrire un seul enregistrement.
• Les horodatages de lot par importation marquent chaque enregistrement afin qu'une annulation complète soit à portée de clic si l'importation est erronée.
• Annulation synchrone pour les petites importations et annulation par lots asynchrone pour les très grandes.
• Format de date configurable (ISO, MM/JJ/AAAA, JJ/MM/AAAA) pour les CSV de différentes régions.
• Remplacement facultatif des donateurs et des dons en double lors de la réimportation.
• Utilisation facultative des montants convertis de Donorbox pour les sites multi-devises.
• Nettoyage sous 24 heures des importations abandonnées, de sorte qu'un onglet de navigateur fermé ne laisse pas de fichiers intermédiaires derrière.
• Le garde de concurrence empêche deux importations de s'exécuter en même temps.

Pourquoi utiliser l'importateur Donorbox ?

Quitter Donorbox sans perdre votre historique était, jusqu'à présent, un exercice manuel de manipulation de feuilles de calcul.

L'importateur Donorbox lit les mêmes CSV que Donorbox exporte lui-même, les fait correspondre au modèle de données de Charitable, et importe tout en un seul flux guidé.

Vos donateurs, vos campagnes et l'historique des dons qui prouve la relation atterrissent tous dans Charitable, où ils peuvent alimenter les e-mails de remerciement, les campagnes de réengagement segmentées et vos rapports en cours.

Exigences

• Charitable Pro 1.8.14 ou version ultérieure
• PHP 7.4 ou supérieur (l'importateur vérifie et refuse de s'exécuter en dessous de cette version)
• Sauvegarde récente de la base de données (fortement recommandée avant toute importation importante)
• Compte Donorbox avec permission d'exporter les dons, les supporters et les plans récurrents au format CSV

Démarrage

Avant de commencer, connectez-vous à votre tableau de bord Donorbox et exportez vos données au format CSV en utilisant l'option « Toutes les colonnes » :

• CSV des dons (requis)
• CSV des supporters (facultatif mais recommandé)
• CSV des plans récurrents (facultatif)

Important : Sauvegardez votre base de données WordPress. Vous pouvez utiliser un outil comme Duplicator pour effectuer une sauvegarde rapide de votre site web.

Sachez que les jetons de paiement Donorbox ne sont pas portables. Les plans récurrents importés sont uniquement archivés et arrivent dans Charitable avec un statut annulé. Vous devrez redemander l'autorisation de paiement à ces donateurs si vous souhaitez que la facturation récurrente se poursuive dans Charitable.

Où trouver l'importateur Donorbox

Dans votre administration WordPress, allez dans Charitable → Outils → Importation → Donorbox.

Commencez à migrer vers Charitable

L'importateur Donorbox est un assistant en six étapes. Chaque étape attend une confirmation explicite avant de passer à la suivante, et l'exécution à blanc peut être répétée autant de fois que vous le souhaitez avant de valider.

Étape 1 : Télécharger les CSV

Téléchargez votre CSV des dons Donorbox. Les CSV des supporters et des plans récurrents sont facultatifs mais fortement recommandés. Une fois que vous cliquez sur Continuer, l'importateur analyse les en-têtes, détecte le délimiteur (virgule, point-virgule ou tabulation) et fait correspondre les colonnes au schéma Donorbox.

Étape 2 : Prévisualiser les décomptes

Une exécution à blanc s'exécute sur vos fichiers téléchargés et signale le nombre de donateurs, de campagnes, de dons et de plans récurrents trouvés. Rien n'est écrit dans votre base de données à ce stade. Utilisez les décomptes pour vérifier que l'importation voit ce que vous attendez.

Étape 3 : Options d'importation

Choisissez les entités à importer et configurez le comportement avancé :

• Ce qu'il faut importer : Donateurs, Campagnes, Dons, Plans récurrents
• Remplacer les doublons lors de l'importation
• Utiliser les montants convertis de Donorbox (pour les sites multi-devises)
• Exécution à blanc (aperçu uniquement, rien n'est écrit)
• Format de date : ISO (AAAA-MM-JJ), MM/JJ/AAAA, ou JJ/MM/AAAA

Étape 4 : Importation

L'importateur traite une phase à la fois (donateurs, puis campagnes, puis récurrents, puis dons) par lots de 200 lignes par défaut. La progression est mise à jour en direct dans le navigateur, et chaque enregistrement importé est marqué avec l'ID du lot d'importation.

Étape 5 : Résultats

Un résumé affiche le nombre d'enregistrements importés, ignorés et erronés pour chaque entité, ainsi que les avertissements. À partir de là, vous pouvez conserver l'importation ou déclencher une annulation.

Étape 6 : Annulation (facultatif)

Si l'importation n'est pas celle que vous attendiez, le bouton Annuler supprime tout ce qui est marqué avec l'ID de lot de cette importation. Les petites importations s'exécutent de manière synchrone ; les très grandes importations (plus de 5 000 enregistrements par défaut) s'exécutent en lots d'arrière-plan.

Lorsque vous annulez, un message d'avertissement s'affiche pour confirmer votre décision. Ainsi, vous ne lancez pas accidentellement une annulation.

Options de configuration

Options d'importation (Étape 3)

Option	Type	Défaut	Description
Importer les donateurs	booléen	vrai	Traiter le CSV des donateurs (lorsqu'il est téléchargé) pour créer des enregistrements de donateurs.
Importer les campagnes	booléen	vrai	Créer des campagnes caritatives à partir de noms de campagnes uniques dans l'exportation des dons.
Importer les dons	booléen	vrai	Créer des enregistrements de dons liés aux donateurs et aux campagnes.
Importer les plans récurrents	booléen	vrai (lorsque le CSV des plans est téléchargé)	Créer des enregistrements de plans récurrents d'archivage (statut annulé).
Ignorer les doublons	booléen	faux	Lorsqu'il est coché, réimporter un enregistrement met à jour celui existant au lieu de le sauter.
Utiliser les montants convertis	booléen	faux	Utiliser la colonne de montant converti de Donorbox au lieu de la devise de don d'origine.
Simulation	booléen	faux	Lire et analyser tout sans écrire d'enregistrement dans la base de données.
Format de date	chaîne de caractères	iso	iso (AAAA-MM-JJ), mdy (MM/JJ/AAAA), ou dmy(JJ/MM/AAAA).

Champs Donorbox importés

CSV des dons (requis)

ID du don, e-mail/prénom/nom du donateur, montant, montant converti, devise, date du don, statut du don, mode de paiement, ID de transaction Stripe/PayPal, frais de traitement, montant du remboursement, nom et ID de la campagne, commentaire, indicateur anonyme, aide aux dons, employeur, profession, indicateur récurrent, ID du plan, adresse complète, téléphone, source/medium/campagne UTM, adresse IP.

CSV des donateurs (facultatif)

E-mail du donateur, prénom/nom, adresse complète, téléphone, employeur, profession, date d'adhésion, ID du donateur Donorbox, nombre total de dons, montant total.

CSV des plans récurrents (facultatif)

ID du plan Donorbox, e-mail du donateur, prénom/nom, nom de la campagne, montant, devise, fréquence, date de début, date de la prochaine facturation, statut, mode de paiement, nombre de dons.

L'importateur accepte plusieurs alias pour chaque champ (par exemple email, donor_email, email_address sont tous mappés à l'e-mail du donateur), donc les exportations plus anciennes ou renommées fonctionnent généralement sans nettoyage manuel.

Personnalisation

Taille du lot

La taille de lot par défaut est de 200 lignes par requête. Définissez CHARITABLE_DONORBOX_BATCH_SIZE dans wp-config.php pour un remplacement à l'échelle de l'environnement, ou utilisez le filtre charitable_donorbox_batch_size pour un contrôle plus fin :

add_filter( 'charitable_donorbox_batch_size', function( $size ) {
    return 500;
} );

Dépannage

« Une autre importation Donorbox est déjà en cours »

L'importateur ne permet qu'une seule importation à la fois. Attendez que l'importation existante se termine, ou utilisez le flux d'annulation sur l'importation existante avant d'en commencer une nouvelle.

« Version PHP non prise en charge »

L'importateur nécessite PHP 7.4+. Mettez à jour PHP dans votre panneau de contrôle d'hébergement et rechargez la page.

Colonnes CSV non reconnues

Ré-exportez depuis Donorbox en utilisant l'option « Toutes les colonnes ». Donorbox modifie occasionnellement les noms d'en-tête ; si votre exportation utilise un en-tête que l'importateur ne reconnaît pas, utilisez le hook charitable_donorbox_csv_schema pour étendre la liste autorisée.

Les plans récurrents sont importés comme annulés

C'est intentionnel. Les jetons de paiement Donorbox ne sont pas portables, donc les plans sont importés comme des enregistrements historiques d'archivage. Pour reprendre la facturation récurrente dans Charitable, vous devrez ré-collecter l'autorisation de paiement de ces donateurs en utilisant un formulaire de don récurrent Charitable.

L'importation semble incorrecte ; comment puis-je l'annuler ?

Utilisez le bouton Annuler sur l'écran Résultats. L'importateur marque chaque enregistrement qu'il crée avec l'ID de lot de l'importation et l'annulation ne supprime que ces enregistrements.

Ressources pour les développeurs

Hooks et filtres

• charitable_donorbox_batch_size — modifiez le nombre de lignes CSV traitées par requête AJAX (par défaut 200).
• charitable_donorbox_csv_schema — étendez ou remplacez la liste autorisée des colonnes par type d'entité (donations, supporters, plans).
• charitable_donorbox_rollback_async_threshold — modifiez le nombre d'enregistrements au-dessus duquel l'annulation s'exécute de manière asynchrone (par défaut 5 000).
• charitable_donorbox_verbose_logging — activez la journalisation interne détaillée pour l'importation active.

Constantes

• CHARITABLE_DONORBOX_BATCH_SIZE — définissez dans wp-config.php pour un remplacement de la taille de lot au niveau de l'environnement.

Classes Utiles

• Charitable_Donorbox_Importer — orchestrateur principal. L'ordre des phases est donateurs → campagnes → récurrents → dons.
• Charitable_Donorbox_CSV_Parser — analyseur CSV en flux avec détection du délimiteur, normalisation des en-têtes et listes autorisées de schémas par entité.

Journalisation

Les événements d'importation sont enregistrés avec la source donorbox et apparaissent dans les journaux standard de Charitable (Charitable → Outils → Journaux), filtrables par la source d'importation Donorbox.

Questions fréquemment posées

Dois-je reformater mon CSV Donorbox avant de l'importer ? 

Dans la plupart des cas, non. Exportez vos données de Donorbox en utilisant l'option « Toutes les colonnes » et téléchargez le fichier tel quel. L'importateur reconnaît plusieurs alias d'en-tête par champ, donc les exportations plus anciennes ou renommées fonctionnent généralement sans aucune correction manuelle.

L'importation affectera-t-elle mon site en direct pendant son exécution ? 

L'importateur traite les enregistrements par lots en arrière-plan, donc votre site reste en ligne. Cependant, nous vous recommandons fortement de faire une sauvegarde complète de la base de données avant d'exécuter une importation importante, juste au cas où.

Qu'advient-il de mes donateurs récurrents ? 

Les plans récurrents sont importés comme des enregistrements d'archivage avec un statut annulé. Les jetons de paiement Donorbox ne sont pas portables, donc la facturation active ne peut pas être transférée. Pour reprendre les dons récurrents dans Charitable, vous devrez ré-collecter l'autorisation de paiement de ces donateurs en utilisant un formulaire de don récurrent Charitable.

Puis-je prévisualiser l'importation avant de valider ? 

Oui. Le mode simulation lit et analyse vos fichiers CSV et rapporte exactement ce qui serait importé – donateurs, campagnes, dons et dons récurrents – sans écrire un seul enregistrement dans votre base de données. Vous pouvez l'exécuter autant de fois que vous le souhaitez avant de valider.

Et si j'importe quelque chose par erreur ? 

Utilisez le bouton Annuler sur l'écran Résultats. L'importateur estampille chaque enregistrement qu'il crée avec un identifiant de lot unique, de sorte que l'annulation ne supprime que ce que cette importation a créé et rien d'autre. Les petites importations sont annulées instantanément ; les très grandes importations exécutent l'annulation en arrière-plan.

Puis-je exécuter l'importateur plus d'une fois ? 

Oui, mais une seule importation peut s'exécuter à la fois. Si vous devez réimporter, attendez que l'importation en cours se termine ou annulez-la d'abord. Activez l'option Ignorer les doublons si vous souhaitez que les enregistrements réimportés mettent à jour ceux existants plutôt que d'être ignorés.

Mes colonnes CSV ne sont pas reconnues. Que dois-je faire ? 

Réexportez depuis Donorbox en utilisant l'option « Toutes les colonnes », car Donorbox change occasionnellement les noms des en-têtes. Si le problème persiste, un développeur peut utiliser le filtre charitable_donorbox_csv_schema pour ajouter les noms de colonnes non reconnus à la liste autorisée.

L'importateur prend-il en charge les formats de date non américains ? 

Oui. Vous pouvez choisir parmi trois formats de date à l'étape Options d'importation : ISO ($YYYY\text{–}MM\text{–}DD$AAAA–MM–JJ), MM/JJ/AAAA ou JJ/MM/AAAA, pour correspondre au format utilisé par votre CSV.

Que se passe-t-il si je ferme l'onglet du navigateur en cours d'importation ? 

Tous les fichiers intermédiaires restants sont automatiquement nettoyés après 24 heures. Le garde de concurrence empêchera également une nouvelle importation de démarrer tant que celle abandonnée ne sera pas effacée.

Ai-je besoin des CSV Supporters et Recurring Plans ? 

Seul le CSV Donations est requis. Les CSV Supporters et Recurring Plans sont facultatifs mais fortement recommandés – le CSV Supporters apporte des données de profil de donateur plus riches, et le CSV Recurring Plans garantit que vos enregistrements de dons récurrents historiques sont préservés.

De quelle version de Charitable Pro ai-je besoin ? 

L'importateur Donorbox est disponible dans Charitable Pro 1.8.14 et versions ultérieures. Vous aurez également besoin de PHP 7.4 ou supérieur sur votre serveur.