ProDon:Intégration aux formulaires de dons en ligne

Intégration aux formulaires de dons en ligne

Version imprimable

---

Cette documentation nécessite le module « Dons en ligne » de Prodon, il faut donc posséder ce module pour avoir accès à ces fonctionnalités.

Définition des méthodes d’intégration possibles

1. Lien

La méthode d’intégration la plus simple vous permettant d’orienter vos donateurs sur vos formulaires de dons en ligne.

Utilisations typiques :

• Intégration à votre site web
• Envoi d’un lien par courriel

Particularités :

• Possibilité d’accéder à la liste de vos formulaires, ou d’accéder directement à un formulaire.
• Pas de programmation requise (ajout d’un hyperlien uniquement)

2. Lien avec envoi d’informations

Une intégration plus avancée permettant de préremplir un formulaire.

Utilisations typiques :

• Intégration à partir d’un microsite
  • Inscription d’équipes / participants
  • Don à une équipe/participant
  • Campagnes virales
• Intégration à partir d’un organisme tiers
  • Firme de télémarketing
  • Firme de développement web
• Intégration à partir d’un système tiers
  • Système maison (gestion de membres, finissants, etc.)

Particularités :

• Programmation requise (exemples fournis)
• Intégration simple par paramètres GET (crypté) ou par paramètres POST
• Possibilité d’envoyer les informations au formulaire afin de le remplir :
  • Informations nominatives
  • Informations sur la transaction (à l’exception des informations de cartes de crédit)
  • Informations personnalisées du formulaire (ex : nom/ID d’équipe, questions spécifiques, etc.)

3. Lien avec envoi d’informations et récupération de la transaction (post-traitement)

Cette intégration inclut les possibilités du « lien avec envoi d’informations » (voir méthode 2) tout en permettant de récupérer la transaction complétée.

Utilisations typiques :

• Intégration à partir d’un microsite en permettant la gestion d’un ou des objectifs
• Permettre au microsite ou à l’organisme tiers de suivre en temps réel la progression des dons

Particularités :

• Programmation requise (exemples fournis)
• Programmation additionnelle requise pour le post-traitement (afin de recevoir les informations de la transaction en format XML)

4. Outils disponibles sur demande

Certains outils sont mis à votre disposition afin d'obtenir certains totaux ou certaines listes de transactions. Attention, l'utilisation de ces outils est facturable.

Frais d'utilisation

Il n'y a aucuns frais relié à l'utilisation du « Lien », du « Lien avec envoi d'informations » et du « Lien avec envoi d’informations et récupération de la transaction (post-traitement) ».

Il y a un frais relié à l'utilisation des « Outils disponibles sur demande ». Comme ces outils peuvent générer du trafic important et solliciter des ressources importantes, un frais est facturé pour chaque appel. Nous vous recommandons de privilégier l'utilisation du post-traitement, et de limiter les appels à ces outils sur demande.

Explications techniques

1. Lien

Format du lien :

https://www.jedonneenligne.org ou https://www.imakeanonlinedonation.org /REP_ORG[_test]/FORM 

Définition :

• REP_ORG : Répertoire de l’organisme sur JeDonneEnLigne ou IMakeAnOnlineDonation
• /REP_ORG : liste des formulaires
• [_test] : Mode test actif (non spécifié = mode production)
• /REP_ORG/FORM : Code du formulaire à appeler

Exemples de liens :

• Liste des formulaires : https://www.jedonneenligne.org/logilys

• Formulaire GEN : https://www.jedonneenligne.org/logilys/GEN
• Formulaire GEN (mode test) : https://www.jedonneenligne.org/logilys_test/GEN

2. Lien avec envoi d’informations

Ce type d’intégration nécessite des capacités de programmation.

• Prototype pour ProDon 5.0.5.x (version 2.1.2 du site JeDonneEnLigne) :
  • https://www.jedonneenligne.org/tools/integration_prototype/v2.1.2/integration_prototype.php
  • Téléchargement des sources: https://www.jedonneenligne.org/tools/integration_prototype/v2.1.2/integration_prototype.zip

• Prototype pour ProDon 5.0.6.x (version 2.1.3 du site JeDonneEnLigne) :
  • https://www.jedonneenligne.org/tools/integration_prototype/v2.1.3/integration_prototype.php
  • Téléchargement des sources: https://www.jedonneenligne.org/tools/integration_prototype/v2.1.3/integration_prototype.zip

• Prototype pour ProDon 5.0.7.x (version 2.1.4 du site JeDonneEnLigne) :
  • https://www.jedonneenligne.org/tools/integration_prototype/v2.1.4/integration_prototype.php
  • Téléchargement des sources: https://www.jedonneenligne.org/tools/integration_prototype/v2.1.4/integration_prototype.zip
  • *** ATTENTION *** Ce package contient la version à jour de la fonction de cryptage pour PHP 7 et plus.

Voici la liste des paramètres possibles dans le prototype :

• Clé : Clé de cryptage unique par organisme. La clé de cryptage pour l'intégration est configurable dans ProDon. Allez dans « Gestion des formulaires Web », « Configurer votre site Web », « Accès JeDonneEnLigne » puis vous allez voir « Clé de cryptage ».

• Répertoire : Répertoire de l’organisme sur JeDonneEnLigne. Ajoutez « _test » pour activer le mode test.
• Code : Code du formulaire à utiliser pour l’envoi d’informations.
• Informations nominatives démontrées en exemple : Pays, Appellation, Prénom, Nom, Adresse, Ville, Province (FrmProvinceUID), Code Postal, Courriel, Téléphone résidence.
• Informations sur la transaction démontrées en exemple : Montant, Activité (FrmActUID), Mode de paiement (FrmPaiUID) et Reçu (FrmReceipt).
• Les paramètres « UID » de FrmCountryUID (liste des pays) et FrmProvinceUID (liste des provinces) sont globaux, ils peuvent être facilement trouvés en inspectant le code source du formulaire.
• Les autres paramètres « UID » sont spécifiques au formulaire, ils peuvent être facilement trouvés en inspectant le code source du formulaire.

Vous pouvez aussi télécharger les sources complètes du prototype en cliquant sur « download sources ». Voici le contenu du fichier zip :

• integration_prototype.php : le code source du prototype
• integration_js_prototype.php : autre exemple, mais en javascript
  • encode64.js, mcrypt.js, rijndael.js : utilisé par integration_js_prototype.php
• parameters.xls : descriptions sommaires des paramètres possibles.
• callback.php, callback.txt : exemple de code afin de récupérer la transaction (voir point 3).
• callback_definition.xls, callback.xml : définition des champs du XML de la transaction retournée et exemple en XML (voir point 3).

3. Lien avec envoi d’informations et récupération de la transaction (URL de post-traitement)

Ce type d’intégration nécessite des capacités de programmation.

Voir au préalable les explications techniques du « lien avec envoi d’informations ». Cette intégration permet de récupérer la transaction lorsqu'elle est complétée avec succès. Il n'y a aucuns frais à l'utilisation de l'URL de post-traitement.

Les informations sur la transaction vous seront transmises (POST) en format XML (crypté avec la clé) sur l’URL de votre choix (configuré dans ProDon, voir ici-bas).

Configuration d'une adresse URL de post-traitement dans ProDon

Pour configurer votre adresse URL de post-traitement, à partir de la fiche de modification d'un formulaire Web avec ProDon, allez dans « Options avancées », « Intégration à JDEL » puis « Configuration de l'adresse URL pour l'intégration post-traitement ».

Paramètre additionnel entrant (facultatif) à passer lors de l’appel au formulaire :

• PersonalId (non crypté) : Identifiant unique pour votre transaction, exemple : &PersonalId=00000001 (non crypté).

Paramètres sortants envoyés sur l'adresse URL de post-traitement :

• trx_xml (crypté) : xml de la transaction. Voir les fichiers « callback_definition.xls » et « callback.xml » dans les sources du prototype pour un exemple.
• mode (non crypté) : Contient « TEST » ou « PROD » selon si la transaction a été effectuée en mode test ou production.
• PersonalId (non crypté) : Votre identifiant unique.
• Attention : L'appel est effectué avec le « UserAgent » suivant : Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:40.0) Gecko/20100101 Firefox/40.1.0 Waterfox/40.1.0.

4. Outils disponibles sur demande

Ce type d’intégration nécessite des capacités de programmation.

Attention, l'utilisation de ces outils est facturable.

Configuration d'un accès aux outils d'intégration sur demande avec ProDon

Pour configurer un accès, dans ProDon, allez dans « Gestion des formulaires Web », « Configurer votre site Web », « Accès JeDonneEnLigne », puis « Ajouter un accès ». Vous devrez spécifier un courriel, cocher la case « Intégration sur demande » puis spécifier un « Mot de passe pour l'intégration ».

Procédure d'appel

https://www.jedonneenligne.org ou https://www.imakeanonlinedonation.org /REP_ORG[_test] /web.integration.php

Définition :

• REP_ORG : Répertoire de l’organisme sur JeDonneEnLigne ou IMakeAnOnlineDonation
• [_test] : Mode test actif (non spécifié = mode production). Il n'y a aucuns frais pour les appels en mode test.

Paramètre POST à spécifier :

• username : Le courriel configuré dans ProDon
• password : Le mode de passe configuré dans ProDon
• type : Type de rapport
  • 0 : Nombre et total des transactions entre 2 dates
  • 1 : Liste des transactions entre 2 dates
  • 2 : Transaction par identifiant unique
• startdate¹ : Date de début (Y-m-d H:i:s)
• enddate¹ : Date de fin (Y-m-d H:i:s)
• frm_code¹ : Code du formulaire (* = tous les formulaires)
  • On peut utiliser aussi frm_uid qui est le id unique du formulaire
• PersonalId² : identifiant unique de la transaction à récupérer

Légende :

• 1: requis pour type 0 et 1
• 2: requis pour type 2

Mise à jour à partir de ProDon 5.0.4.x

Si vous avez déjà une intégration fonctionnelle avec ProDon 5.0.4.x, veuillez prendre connaissances des changements :

1. Modification à la structure du XML retourné pour une transaction :
   1. Les options 1 à 10 ont été retirées (del_trx_par_option1 à del_trx_par_option10) dans le noeud <del_trx_participant>
   2. Ajout des champs del_trx_par_home, del_trx_par_office, del_trx_par_extension, del_trx_par_cellular, del_trx_par_personal_email, del_trx_par_corporate_email dans le noeud <del_trx_participant>
   3. Ajout des champs del_trx_customization_key_name et del_trx_customization_key_uid dans noeud <del_trx_customization>
   4. Ajout du champ del_trx_paysafe_transactionid.

Mise à jour à partir de ProDon 5.0.3.x

Si vous avez déjà une intégration fonctionnelle avec ProDon 5.0.3.x, veuillez prendre connaissances des changements :

1. Modification à la structure du XML retourné pour une transaction :
   1. Nouveau champ ajouté : del_frm_code.

Mise à jour à partir de ProDon 5.0.2.x

Si vous avez déjà une intégration fonctionnelle avec ProDon 5.0.2.x, veuillez prendre connaissances des changements à effectuer :

1. La clé de cryptage pour l'intégration est maintenant configurable dans ProDon. Allez dans « Gestion des formulaires Web », « Configurer votre site Web », « Accès JeDonneEnLigne », « Clé de cryptage ». Si vous aviez déjà une clé de cryptage, vous la verrez à cet endroit, sinon il vous sera possible d'en générer une.
2. Le paramètre PersonalUrl n'existe plus, pour configurer une adresse URL de post-traitement, vous devez avoir une clé de cryptage (tel qu'expliqué ci-dessus), et vous devez configurer votre adresse URL dans le ou les formulaires en question. À partir de la fiche de modification d'un formulaire Web avec ProDon, allez dans « Options avancées », « Intégration à JDEL » puis « Configuration de l'adresse URL pour l'intégration post-traitement ».
3. Avec ProDon 5.0.2.x, le UserAgent était vide, mais maintenant nous utilisons le UserAgent suivant lors du POST sur l'adresse URL de post-traitement : Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:40.0) Gecko/20100101 Firefox/40.1.0 Waterfox/40.1.0.
4. Les outils web.trx.php (récupérer une transaction par id), totalamount_report.php (obtenir le nombre et le montant total des transactions) et custom_report.php (récupérer des transactions par date) ont été remplacé par des nouveaux outils disponibles sur demande, configurable dans ProDon, voir la documentation.
5. Modification à la structure du XML retourné pour une transaction :
   1. Les champs suivants ont été remplacés : "del_trx_country" devient "del_trx_address_country", "del_trx_country_uid" devient "del_trx_address_country_uid", "del_trx_province" devient "del_trx_address_province", "del_trx_province_uid" devient "del_trx_address_province_uid", "del_trx_city" devient "del_trx_address_city", "del_trx_postalcode" devient "del_trx_address_postalcode".
   2. Nouveaux champs ajoutés : del_trx_address_format_uid, del_trx_address_roadno, del_trx_address_roadtype, del_trx_address_roadtype_uid, del_trx_address_road, del_trx_address_direction, del_trx_address_direction_uid, del_trx_address_pointcalltype, del_trx_address_pointcalltype_uid, del_trx_address_pointcallno, del_trx_address_buildinglocation, del_trx_address_roadlocationtype, del_trx_address_roadlocationtype_uid, del_trx_address_roadlocationno.
   3. Référez-vous aux fichiers "callback_definition.xls" et "callback.xml" du prototype
6. Il faut maintenant utiliser le noeud "del_frm_customization_uid" au lieu de l'attribut "uid" qui se trouve dans le noeud "del_trx_customization".

Mise à jour à partir de ProDon 4.7.3.x

Si vous avez déjà une intégration fonctionnelle avec ProDon 4.7.3.x, veuillez prendre connaissances des changements :

• Les paramètres « PersonnalKey », « PersonnalUrl » et « PersonnalId » ont été renommés en « PersonalKey », « PersonalUrl » et « PersonalId » (retrait d'un « n » superflu).
• Les paramètres « UID » de FrmCountryUID (liste des pays) et FrmProvinceUID (liste des provinces) ont été modifiées car ils sont maintenant globaux.
• Le mode test s'active désormais avec /REP_ORG[_test] au lieu de /REP_ORG[/test].

---

Nom du document : ProDon:Intégration aux formulaires de dons en ligne

Version imprimable