Créez des intégrations Apple Wallet (.pkpass) et Google Wallet à grande échelle. Émettez, mettez à jour, validez et diffusez des notifications en direct via des API REST prêtes pour la production.
La gestion des cartes suit un cycle en 6 étapes : 1. Modèle (gabarit visuel) → 2. Carte (enregistrement signé cryptographiquement) → 3. Distribution (passAccessUrl sécurisée) → 4. Enregistrement Wallet (l'appareil s'inscrit auprès d'APNs / Google Push) → 5. Mises à jour en direct (notifications sur écran verrouillé) → 6. Scan et télémétrie d'utilisation (validation et webhooks en temps réel).
1. ModèlePOST /api/v1/templates
Mise en page maître, type de code-barres, couleurs de marque et champs de schéma
Concepts clés
Mécaniques de cartes & moteur de fidélité
Associez des mécaniques métier persistantes aux modèles sur 8 solutions clés en main (Fidélité, Cartes à tampons, Coupons, Cartes cadeaux/prépayées, Billets d'événement, Adhésions, Badges employés, Cartes VIP). Les règles s'exécutent de manière atomique au scan ou via API.
LOYALTY_PROGRAM
LOYALTY_PROGRAM & Paliers
Cumul de points par scan (defaultChangeValue) avec progression automatique de palier
STAMP_CARD
STAMP_CARD_ADD / DEDUCT
Suit le nombre de tampons (0..maximumValue) avec onCap ('noop' | 'reset') et rewardClaimBehavior
PREPAID_CARD
Grand livre PREPAID_CARD
Comptabilité de grand livre prépayé en sous-unités ISO 4217 avec application de disallowNegativeBalance
VALID_ONCE_PER_DAY
VALID_ONCE_PER_DAY & RENEW
Limites de passage quotidiennes par fuseau horaire et prolongation automatique d'expirationDate au scan
Gestion des cartes
11 points de terminaison
POSThttps://api.passinstance.com/api/v1/passesClé API
Gestion des cartes
Émettre une nouvelle carte
Créez et émettez une nouvelle carte Apple Wallet (.pkpass) et Google Wallet à partir d'un modèle avec champs client, code-barres et valeurs dynamiques.
En-têtes2 requis • 1 optionnel(s)
X-API-Keystring
Requis
Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.
Exemple : pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Requis
Doit être application/json.
Exemple : application/json
Paramètres de requête2 optionnel(s)
Charge utile Charge utile de requête contenant l'ID de modèle, le numéro de série unique, les valeurs client et la configuration optionnelle du code-barres.
Corps de la requête1 requis • 15 optionnel(s)
templateIdstring (UUID)
Requis
ID du modèle pour la carte.
Exemple : tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
POSThttps://api.passinstance.com/api/v1/passes/upsert-by-external-idClé API
Gestion des cartes
Créer ou mettre à jour par ID externe (Upsert)
Créer ou mettre à jour de manière idempotente une carte indexée par (customerId, externalId) pour une synchronisation fluide avec votre CRM, TPV ou e-commerce.
En-têtes1 requis
X-API-Keystring
Requis
Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.
Exemple : pi_live_98a7b6c5d4e3f2a1
Charge utile de requête contenant templateId, externalId et les attributs dynamiques de la carte.
Corps de la requête2 requis • 3 optionnel(s)
templateIdstring (UUID)
Requis
UUID du modèle cible.
Exemple : tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
externalIdstring
Requis
Identifiant externe CRM/TPV stable et unique dans votre espace de travail.
POSThttps://api.passinstance.com/api/v1/passes/{id}/useClé API
Gestion des cartes
Appliquer une action mécanique
Exécuter une opération atomique sur une carte : INCREMENT (carte à tampons), DECREMENT, DEBIT (solde prépayé), CREDIT ou VALIDATE (coupon à usage unique).
En-têtes3 requis
X-API-Keystring
Requis
Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.
Exemple : pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Requis
Doit être application/json.
Exemple : application/json
Idempotency-Keystring
Requis
UUID obligatoire garantissant l'exécution atomique et évitant toute double déduction de solde ou de tampon.
Exemple : 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Paramètres de chemin1 requis
idstring (UUID)
Requis
UUID unique de la carte ciblée.
Exemple : pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
Charge utile de requête contenant l'action mécanique, le montant décimal optionnel, l'ID opérateur et le lieu.
Corps de la requête1 requis • 4 optionnel(s)
actionstring (enum)
Requis
INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE ou NOOP.
Résoudre une page publique de téléchargement de carte par slug (GET /d/{slug}/info sans préfixe). Pour une recherche authentifiée côté gestion, utilisez GET /api/v1/download-pages/slug/{slug}.
Paramètres de chemin1 requis
slugstring
Requis
Slug unique de la page de téléchargement hébergée.
POSThttps://api.passinstance.com/api/v1/passes/{id}/notificationsClé API
Notifications push
Envoyer une notification sur écran verrouillé
Envoyer immédiatement une notification push sur l'écran verrouillé à une carte Apple Wallet (.pkpass) ou Google Wallet installée. Pour les envois planifiés ou personnalisation d'en-tête, utilisez POST /api/v1/push-notifications/passes/{id}.
En-têtes1 requis
X-API-Keystring
Requis
Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.
Exemple : pi_live_98a7b6c5d4e3f2a1
Paramètres de chemin1 requis
idUUID
Requis
UUID unique de la carte destinataire de la notification.
Exemple : 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
Charge utile de requête contenant le corps du message et un titre d'en-tête optionnel.
Corps de la requête1 requis • 1 optionnel(s)
messagestring
Requis
Message texte affiché sur l'écran verrouillé de l'utilisateur.
Exemple : Your reward points have been updated! You now have 250 points.