Premiers pas avec l'API de Zeffy

Ce guide vous accompagne dans la configuration. Pour tous les détails techniques sur chaque point de terminaison, champ et paramètre, consultez la documentation de l'API de Zeffy.

Que pouvez-vous faire avec l'API ?

L'API de Zeffy vous donne un accès en lecture à trois éléments clés de votre compte :

Paiements : récupérez la liste de toutes vos transactions ou cherchez un paiement précis. Filtrez par devise, statut, type (en ligne, manuel ou importé), contact, campagne ou période. Chaque paiement contient les articles, les détails de remboursement, les informations sur l'acheteur et un lien vers le reçu fiscal.

Contacts : récupérez la liste complète de vos donateurs et sympathisants, ou cherchez une personne précise par identifiant ou par courriel. Chaque contact contient l'historique des dons, le total des contributions, l'adresse et les préférences de communication.

Campagnes : accédez à vos formulaires de don, à vos événements et à vos autres types de campagnes. Consultez les titres, les descriptions, les objectifs, les dates, les occurrences et les montants amassés.

Quelques exemples d'utilisation par les organismes

• Synchroniser les nouveaux dons en temps réel avec un système comptable comme QuickBooks ou Xero

• Garder un CRM comme Salesforce ou HubSpot à jour avec les dernières informations sur les donateurs

• Créer des tableaux de bord ou des rapports personnalisés qui combinent les données de Zeffy avec celles d'autres sources

• Automatiser des processus de remerciement ou des avis internes à la réception d'un paiement

Qui peut accéder à l'API ?

Seuls les administrateurs peuvent générer des clés d'API. Si vous êtes membre d'un organisme sans droits d'administrateur, demandez à l'administrateur de votre organisme de s'en occuper.

Les organismes sur Zeffy n'ont qu'un seul administrateur. Si vous voulez transférer le statut d'administrateur à un autre membre de votre compte, suivez les étapes décrites dans cet article.

Si vous ne voyez pas Intégrations dans vos Paramètres, ou si la page reste vide quand vous essayez d'obtenir une clé d'API, vous êtes probablement connecté avec un utilisateur qui n'est pas l'administrateur. Demandez à votre administrateur de générer la clé et de vous la transmettre de façon sécuritaire.

Une clé d'API est toujours liée à un compte d'organisme actif et vérifié. Nous ne pouvons pas fournir directement un accès à l'API, ni le fournir à une personne qui n'a pas de compte d'organisme : c'est l'administrateur de l'organisme qui doit générer la clé.

Obtenir votre clé d'API

1. Connectez-vous à votre compte Zeffy et allez dans Paramètres → Intégrations.
   
   

   

2. Dans la section Intégrations, vous trouverez l'option pour générer une clé d'API. Nous vous poserons d'abord quelques questions pour mieux comprendre vos besoins.
   
   

   

   
   

3. Ouvrez l'onglet de la clé d'API et cliquez sur Générer pour créer votre clé d'API. Copiez votre clé et conservez-la en lieu sûr. Vous l'utiliserez pour authentifier chacune de vos requêtes à l'API. Les webhooks se configurent séparément, dans l'onglet des webhooks (voir plus bas).

Important : traitez votre clé d'API comme un mot de passe. Ne la partagez pas publiquement et ne l'incluez pas dans du code côté client. Toute personne qui a votre clé peut lire les données de votre organisme.

Par défaut, votre clé est masquée sur la page. Cliquez sur Afficher la clé pour l'afficher ou la copier.

Générer une nouvelle clé d'API

Générer une nouvelle clé dans Paramètres → Intégrations invalide immédiatement l'ancienne : mettez donc à jour tous les outils qui l'utilisent. Il n'existe pas d'autre façon de réinitialiser une intégration à partir de Zeffy. Une nouvelle clé ne change rien dans l'outil qui reçoit vos données : si une intégration cesse de fonctionner, vérifiez ses paramètres dans cet outil (le point de terminaison, l'en-tête Authorization, l'URL du webhook et l'association des champs).

Faire votre première requête

Chaque requête à l'API doit contenir votre clé dans l'en-tête Authorization, sous forme de jeton Bearer. Voici à quoi ressemble une requête :

GET https://api.zeffy.com/api/v1/payments
Authorization: Bearer YOUR_API_KEY

Cette requête renvoie une liste paginée de vos paiements. Par défaut, vous obtenez 10 résultats à la fois (vous pouvez en demander jusqu'à 100).

Pagination

L'API utilise une pagination par curseur. Chaque réponse de type liste contient un champ has_more qui indique s'il reste d'autres résultats, et une valeur next_cursor que vous pouvez passer dans le paramètre starting_after pour obtenir la page suivante.

Filtres

La plupart des points de terminaison de type liste acceptent des filtres pour préciser les résultats. Pour les paiements, vous pouvez filtrer par :

• currency : cad ou usd

• status : succeeded, failed ou pending

• type : online, manual ou imported

• contact : un identifiant de contact précis

• campaign : un identifiant de campagne précis

• created[gte], created[lte], etc. : des périodes exprimées en horodatages Unix

Les contacts peuvent être filtrés par email et par périodes created ou updated. Les campagnes acceptent les filtres de date created.

Configurer des webhooks

Si vous voulez être avisé quand quelque chose se produit plutôt que d'interroger l'API à répétition, les webhooks sont la solution. Ils vous permettent de configurer une URL qui reçoit les événements de votre compte Zeffy, pour automatiser des tâches dans d'autres outils selon votre activité de collecte de fonds.

Pour configurer un webhook :

1. Dans Paramètres → Intégrations, vous trouverez l'option pour configurer une URL de webhook.

2. Inscrivez l'URL où vous voulez recevoir les avis.

3. Quand un paiement est complété, Zeffy envoie une requête POST à votre URL avec tous les détails du paiement.

Le contenu du webhook comprend un type d'événement (payment.completed), un horodatage et l'objet paiement complet.

Votre point de terminaison doit répondre avec un code d'état 2xx pour confirmer la réception. Sinon, Zeffy tente de nouveau l'envoi.

Codes de réponse

Voici ce que signifient les différents codes d'état quand vous utilisez l'API :

• 200 : votre requête a réussi.

• 400 : un des paramètres de votre requête pose problème. Vérifiez vos filtres et leur format.

• 401 : votre clé d'API est manquante ou invalide. Assurez-vous de l'inclure dans l'en-tête Authorization.

• 404 : la ressource recherchée n'existe pas. Vérifiez l'identifiant utilisé.

• 429 : vous avez atteint la limite de requêtes. Ralentissez vos requêtes et réessayez sous peu.

Et Zapier ?

Si vous utilisez déjà Zapier pour connecter Zeffy à d'autres outils, cela fonctionne toujours. L'API est une excellente option si vous avez besoin de plus de contrôle, si vous voulez créer une intégration personnalisée ou si vous travaillez avec un développeur qui peut mettre en place une solution adaptée à vos besoins. Zapier reste la voie la plus simple si vous n'avez pas de ressources techniques et voulez connecter Zeffy à des outils comme Google Sheets, Slack ou Mailchimp.

Prochaines étapes

• Documentation complète de l'API : la référence détaillée de chaque point de terminaison, paramètre et champ de réponse.

Si vous avez des questions ou avez besoin d'aide pour la configuration, écrivez à notre équipe de soutien. Nous sommes là pour vous aider.