Comment utiliser l'API de Zeffy pour intégrer avec d'autres outils

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

Que pouvez-vous faire avec l'API ?

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

Paiements — Récupérez la liste de toutes vos transactions ou recherchez un paiement précis. Filtrez par devise, statut, type (en ligne, manuel ou importé), contact, campagne ou plage de dates. Chaque paiement inclut les articles, les détails de remboursement, les informations sur l'acheteur ainsi qu'un lien vers le reçu fiscal.

Contacts — Récupérez la liste complète de vos donateurs et sympathisants, ou recherchez une personne précise par ID ou par courriel. Chaque contact inclut l'historique des dons, le total des contributions, l'adresse et les préférences de communication.

Campagnes — Accédez à vos formulaires de dons, événements et autres types de campagnes. Consultez les titres, descriptions, objectifs, dates, 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 Zeffy avec celles d'autres sources

• Automatiser les flux de remerciements ou les notifications 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'une organisation sans droits d'administrateur, vous devrez demander à l'administrateur de votre organisation de configurer cela.

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

Comment obtenir votre clé d'API

1. Connectez-vous à votre compte Zeffy et rendez-vous 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 afin de mieux comprendre vos besoins.

3. Choisissez le type de connexion que vous souhaitez établir (API ou Webhook), puis générez votre clé. Copiez-la et conservez-la dans un endroit sûr. Vous l'utiliserez pour authentifier chacune de vos requêtes à l'API.

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 possède votre clé peut lire les données de votre organisation.

Votre première requête

Chaque requête à l'API doit inclure 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

Cela 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 basée sur un curseur. Chaque réponse de type liste inclut un champ has_more qui indique s'il reste d'autres résultats, ainsi qu'une valeur next_cursor que vous pouvez transmettre dans le paramètre starting_after pour obtenir la page suivante.

Filtres

La plupart des endpoints de liste prennent en charge des filtres pour affiner 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 ID de contact précis

• campaign — un ID de campagne précis

• created[gte], created[lte], etc. — plages de dates au format timestamp Unix

Les contacts peuvent être filtrés par email et par plages de dates created ou updated. Les campagnes prennent en charge les filtres de date created.

Configurer les Webhooks

Si vous préférez être notifié lorsqu'un événement se produit plutôt que d'interroger l'API à répétition, les webhooks sont la solution idéale. Ils vous permettent de configurer une URL qui recevra les événements qui surviennent dans votre compte Zeffy — ce qui vous permet d'automatiser des tâches dans d'autres outils, en fonction de votre activité de collecte.

Pour configurer un webhook :

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

2. Saisissez l'URL à laquelle vous souhaitez recevoir les notifications.

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

La charge utile du webhook inclut un type d'événement (payment.completed), un timestamp et l'objet paiement complet.

Votre endpoint doit répondre avec un code de statut 2xx pour confirmer la réception. À défaut, Zeffy réessaiera la livraison.

Codes de réponse

Voici la signification des différents codes de statut lorsque vous utilisez l'API :

• 200 — Votre requête a été traitée avec succès.

• 400 — Un problème est survenu avec vos paramètres de requête. 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'ID utilisé.

• 429 — Vous avez atteint la limite de requêtes. Ralentissez vos appels et réessayez sous peu.

Qu'en est-il de 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 souhaitez créer une intégration personnalisée, ou si vous travaillez avec un développeur capable de mettre en place une solution sur mesure. Zapier reste le chemin le plus simple si vous n'avez pas de ressources techniques et que vous souhaitez connecter Zeffy à des outils comme Google Sheets, Slack ou Mailchimp.

Prochaines étapes

• Documentation complète de l'API — Référence détaillée pour chaque endpoint, paramètre et champ de réponse.

• Intégrer Zeffy à d'autres plateformes avec Zapier — Si vous préférez une approche sans code.