Utiliser l'API Passtastic | Aide Passtastic
Passtastic
Découvrir
Produit
Application de fidélité
Tarifs
Cas d'usage
Témoignages
Aide
Pas encore de compte ? Commencer gratuitement

Utiliser l'API Passtastic

Ce que l'API vous permet de faire

L'API Passtastic vous permet de connecter vos propres systèmes (une caisse sur mesure, un CRM, une application interne) directement à votre programme de fidélité. Avec elle, vous pouvez :

  • Inscrire des clients et émettre des cartes Wallet depuis votre propre parcours d'inscription
  • Ajouter des tampons ou des points, et consulter le solde d'un client, depuis votre propre caisse ou votre back-office
  • Être averti en temps réel grâce aux webhooks : au lieu d'interroger l'API, Passtastic envoie un événement à votre système à l'instant où quelque chose se produit (un client s'inscrit, une récompense est utilisée, et plus encore)
  • Réutiliser les clients que vous avez déjà : si une personne que votre système inscrit s'est déjà inscrite via votre page d'inscription, Passtastic la reconnaît par e-mail ou téléphone et ajoute votre référence à la carte qu'elle a déjà, au lieu d'en émettre une deuxième

Ceci s'adresse aux entreprises qui réalisent une intégration sur mesure. Si vous voulez simplement une connexion toute prête, voir Connecter Square POS ou Caisses et intégrations : aucun code requis.

L'accès à l'API fait partie du pack Connecter votre caisse. Le pack est activé pendant votre essai gratuit de 14 jours et facturé par établissement ; voir Tarifs. Sans lui, API et webhooks dans Paramètres vous indique comment l'ajouter.

Obtenir une clé API

1. Ouvrez Paramètres, puis API et webhooks (sous Entreprise).

2. Dans l'onglet Clés API, cliquez sur Créer une clé de test pour essayer en toute sécurité, ou sur Créer une clé live quand vous êtes prêt à connecter de vrais clients.

3. Donnez-lui un nom de clé pour savoir plus tard à quoi elle sert (par exemple « CRM de production »).

4. Votre nouvelle clé s'affiche une seule fois, dans la fenêtre Votre nouvelle clé API (Votre nouvelle clé de test pour une clé de test). Copiez-la maintenant : vous ne pourrez plus la revoir. Cliquez sur Copier, ou sur Afficher pour la révéler d'abord.

Traitez cette clé comme un mot de passe. Toute personne qui la possède peut agir sur votre compte via l'API.

5. Conservez la clé en sécurité dans votre propre système (une variable d'environnement, un gestionnaire de secrets) et envoyez-la comme en-tête d'authentification de la requête : voir la référence technique ci-dessous pour le format exact de l'en-tête.

Seuls les administrateurs peuvent créer ou révoquer des clés API.

Essayez d'abord avec une clé de test

Les clés de test fonctionnent sur toutes les formules, y compris pendant votre essai : aucun passage à une formule supérieure n'est nécessaire. Les clients de test reçoivent une vraie carte Wallet marquée TEST et sont supprimés au bout de 30 jours, il n'y a donc rien à nettoyer à la main.

Suivez le Démarrage rapide de la documentation technique avec votre clé de test : il explique comment inscrire un client de test et ajouter une carte à votre propre téléphone, pour que vous voyiez tout le parcours avant qu'il touche un vrai client.

Quand votre intégration fonctionne de bout en bout, revenez à API et webhooks et cliquez sur Créer une clé live pour passer aux vrais clients. Les clés live font partie du pack Connecter votre caisse.

Clé perdue ou compromise ?

Les clés ne sont plus affichées après leur création. Si vous en avez perdu une, ou si vous pensez qu'elle a été exposée, ouvrez Clés API et cliquez sur Révoquer : elle cesse de fonctionner immédiatement. Créez ensuite une nouvelle clé et mettez à jour votre intégration.

Configurer un webhook

Les webhooks permettent à votre système de réagir à l'instant où quelque chose se passe dans Passtastic, sans avoir à interroger l'API en continu.

1. Dans l'onglet Webhooks, cliquez sur Ajouter un point de terminaison.

2. Saisissez l'URL du point de terminaison : l'adresse, sur votre propre système, qui recevra l'événement (par exemple `https://your-system.com/hook`).

3. Sous Événements, choisissez ceux que vous voulez recevoir :

  • Client inscrit
  • Solde mis à jour
  • Niveau modifié
  • Récompense utilisée
  • Carte expirée
  • Carte renouvelée

4. Enregistrez. Votre secret de signature s'affiche une seule fois, dans la fenêtre Secret de signature : copiez-le maintenant. Utilisez-le pour vérifier qu'une requête de webhook vient bien de Passtastic (la référence technique explique comment contrôler la signature).

Seuls les administrateurs peuvent créer ou modifier des webhooks.

Chaque point de terminaison de webhook affiche ses envois récents, pour que vous puissiez voir si un appel a réussi ou échoué, et rejouer un envoi échoué dès que votre système est de nouveau disponible, sans attendre le prochain événement.

Modifier ou désactiver un webhook

Ouvrez le point de terminaison et cliquez sur Modifier pour changer son URL ou ses événements, ou réglez son statut sur Désactivé pour suspendre les envois sans le supprimer. Cliquez sur Supprimer pour le retirer définitivement.

Où trouver la référence technique complète

Ce guide couvre le côté tableau de bord : la création des clés et des webhooks. Pour les points d'accès, les formats de requête et de réponse, les en-têtes d'authentification, les codes d'erreur et les exemples de code, consultez la documentation de l'API complète, ou allez directement à la référence de l'API pour le schéma de requête et de réponse de chaque point d'accès. Vous pouvez aussi accéder aux deux à tout moment avec les liens Lire la documentation de l'API et Référence de l'API en haut de la page API et webhooks ; la référence de l'API s'ouvre dans un nouvel onglet.

Questions fréquentes

Ai-je besoin d'une caisse pour utiliser l'API ?
Non. L'API sert à connecter vos propres systèmes : une caisse sur mesure, un CRM ou une application. Si vous préférez une connexion toute prête, voir Connecter Square POS ou Caisses et intégrations.
Mon intégration va-t-elle créer des clients en double ?
Non. Quand votre système inscrit quelqu'un, Passtastic vérifie d'abord si ce client existe déjà dans votre compte : d'après la référence que votre système envoie, puis l'e-mail, puis le téléphone. S'il existe, il associe votre référence à sa carte existante au lieu d'en émettre une deuxième, et ses tampons et ses points restent où ils sont. Si deux clients partagent le même e-mail ou téléphone, Passtastic ne devine pas : il renvoie une erreur qui nomme les deux, pour que votre développeur choisisse le bon.
Mon système peut-il savoir quand la carte d'un client expire ?
Oui. Si votre carte a une durée de validité (Validité de la carte sous Détails de la carte dans l'onglet Configuration du programme), cochez Carte expirée et Carte renouvelée sur votre webhook : votre système est prévenu quand une carte expire et quand elle est renouvelée, y compris les renouvellements que vous faites dans Passtastic. Votre développeur peut aussi lire la date de fin de chaque client et renouveler une carte depuis votre système. Pour essayer avant qu'une vraie carte n'expire, une clé de test peut faire expirer tout de suite la carte d'un client de test. La documentation de l'API donne les détails.
L'accès à l'API est-il compris dans ma formule ?
Oui, avec le pack Connecter votre caisse : l'API, les webhooks et les clés live en font partie. Le pack est activé pendant votre essai gratuit de 14 jours et facturé par établissement ; voir Tarifs. Sans lui, API et webhooks affiche API pour développeurs avec un bouton Ajouter pour. Si vous retirez le pack, l'API et les webhooks sont mis en pause et rien n'est supprimé. Sur une formule précédente ? Votre formule garde ce qu'elle comprenait ; voir Comprendre les limites de votre formule. Les clés de test fonctionnent sur toutes les formules.
Où trouver l'identifiant d'une carte ?
Ouvrez l'onglet Partager du programme. Sous Partager sur les réseaux sociaux ou votre site web, vous voyez son lien : la partie après `/get-pass/` est l'identifiant de la carte. Ne copiez pas l'identifiant depuis l'adresse de la page du programme, car il peut être différent. Votre développeur peut aussi lister toutes vos cartes et leurs identifiants via l'API (`GET /api/v1/cards`).
Mon développeur obtient « Missing scope(s) : cards:read ». Que faire ?
La clé a été créée avant que l'API puisse lister les cartes. Créez une nouvelle clé (Clés API → Créer une clé), donnez-la à votre développeur, puis Révoquez l'ancienne.
Qui peut gérer les clés API et les webhooks ?
Uniquement les administrateurs. Les éditeurs et les lecteurs ne voient pas l'option pour créer, modifier ou révoquer une clé ou un webhook.
Puis-je avoir plusieurs clés API ?
Oui. Créez une clé distincte par système ou par environnement (par exemple une pour votre CRM, une pour un environnement de test) pour pouvoir en révoquer une sans casser les autres.
Un webhook ne reçoit plus d'événements : que s'est-il passé ?
Ouvrez le point de terminaison et consultez ses envois récents pour connaître la cause de l'échec (par exemple, votre serveur a renvoyé une erreur ou n'a pas répondu à temps). Corrigez le problème de votre côté, puis cliquez sur Rejouer sur l'envoi échoué pour le renvoyer.