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.
L'API Passinstance permet aux développeurs d'émettre, distribuer, mettre à jour et valider dynamiquement des cartes numériques pour Apple Wallet (iOS) et Google Wallet (Android). Toutes les requêtes API s'effectuent en HTTPS et renvoient une enveloppe de réponse API standardisée avec codes d'état lisibles par machine.
URL de base Production
Actif
https://api.passinstance.com/api/v1
URL de base Sandbox Staging
https://staging-api.passinstance.com/api/v1
Format requête et réponseapplication/json (UTF-8) avec enveloppe de réponse standard
Fuseau horaire du serveurEurope/Berlin (horodatages ISO 8601)
Sécurité
Authentification — Clés API et autorisation
Utilisez X-API-Key: <key> ou Authorization: ApiKey <key> pour les points de terminaison acceptant une clé API. Bearer est réservé aux JWT d'accès. Conservez les identifiants côté serveur.
Invariant de sécurité:Serveur à serveur uniquement. Ne jamais intégrer de clés secrètes dans le frontend.
Démarrage rapide
Démarrage rapide — Première requête API
Créez votre première carte utilisable en moins de 5 minutes. Définissez votre en-tête de clé API, appelez POST /api/v1/passes avec un templateId valide et transmettez la passAccessUrl retournée à votre utilisateur final.
Étape 1 : Définir la clé
export PASSINSTANCE_API_KEY="pi_test_..."
Étape 2 : Émettre la carte
POST /api/v1/passes avec templateId et serialNumber
Étape 3 : Récupérer l'URL
Extraire response.data.passAccessUrl de la réponse 201 Created
Étape 4 : Distribuer
Envoyer l'URL par SMS/e-mail ; l'utilisateur appuie sur « Ajouter à Apple/Google Wallet »
Ressources
Collection Postman — Importer et tester les requêtes API
Importez la spécification OpenAPI 3.0 de Passinstance (/api/docs/openapi.json) directement dans Postman, Insomnia ou Bruno pour tester les points de terminaison, inspecter les schémas et générer des clients HTTP typés.
Cliquez sur Importer dans Postman, Insomnia ou Bruno et collez /api/docs/openapi.json pour charger toutes les routes
3. Configurer l'environnement
Définissez baseUrl = https://api.passinstance.com et PASSINSTANCE_API_KEY = pi_test_...
4. Vérifier la connectivité
Exécutez GET /api/v1/templates avec X-API-Key: pour tester votre espace de travail
Opérations et FAQ
FAQ — Questions fréquentes et gestion des erreurs
Chaque réponse utilise l'enveloppe de réponse API standard. Corrigez les erreurs 4xx avant de réessayer ; appliquez un délai sur 5xx et 429 selon l'en-tête Retry-After.
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
Guides plateforme
Matrice Apple Wallet vs. Google Wallet
Passinstance signe automatiquement les archives .pkpass pour iOS et génère des objets JWT signés pour Google Wallet. Les visuels, codes-barres et déclencheurs sur écran verrouillé s'adaptent automatiquement aux deux systèmes.
Apple WalletiOS · .pkpass
Signature Apple Wallet
Signature cryptographique PKCS#7 via certificat Apple Pass Type ID
Google WalletAndroid · JWT
Émetteur Google Wallet
Charge utile REST JWT via compte de service Google Cloud
Parité multi-plateforme (un seul appel REST)iOS + Android
Codes-barres universelsQR Code et PDF417 pris en charge nativement sur les deux plateformes mobiles
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 modèles
7 points de terminaison
GEThttps://api.passinstance.com/api/v1/templatesClé API
Gestion des modèles
Lister tous les modèles
Récupérer une liste paginée des modèles de cartes appartenant à l'espace client authentifié.
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>.
POSThttps://api.passinstance.com/api/v1/templates/{id}/publishClé API
Gestion des modèles
Publier un brouillon de modèle
Promouvoir une révision brouillon (rowKind: DRAFT) vers PUBLISHED, marquer changesToPush: true et planifier les mises à jour APNs et Google Wallet pour toutes les cartes actives.
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
idstring (UUID)
Requis
UUID du modèle à publier.
Exemple : tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Charge utile de requête contrôlant la publication immédiate ou planifiée et la diffusion des mises à jour wallet.
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.
Aperçu — Fonctionnement de la validation des cartes
Chaque scan de code-barres ou NFC exécute un pipeline déterministe de validation en 14 règles (statut, expiration, créneaux horaires, géorepérage, mécaniques, quotas, anti-rejeu) avec nonces cryptographiques optionnels et synchronisation hors ligne.
Nonce anti-rejeu
POST /api/v1/scans/prepare émet un nonce cryptographique anti-rejeu éphémère lié au code-barres
Valider un code-barres optique, QR code ou scan NFC Apple VAS / Google Smart Tap depuis un terminal ou scanner mobile via le moteur à 14 règles.
En-têtes2 requis • 2 optionnel(s)
x-scanner-keystring
Requis
Clé de configuration de scanner provisionnée dans le tableau de bord ou via un lien d'appairage.
Exemple : scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Content-Typestring
Requis
Doit être application/json.
Exemple : application/json
Charge utile Charge utile de requête contenant le code-barres scanné, un nonce anti-rejeu optionnel, les métadonnées canal/protocole et le contexte opérateur.
Corps de la requête1 requis • 8 optionnel(s)
scannedBarcodeValuestring
Requis
Chaîne brute lue depuis le QR code, PDF417, CODE128, AZTEC ou tap NFC.
Aperçu des Webhooks et vérification des signatures
Vérifiez X-Webhook-Signature comme HMAC-SHA256 du corps brut exact de la requête avec le secret de votre abonnement. Utilisez une comparaison en temps constant et un traitement idempotent des événements.
En-tête de signature
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
En-tête d'horodatage
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Protection contre le rejeu
Vérifiez que X-Webhook-Id correspond à eventId signé, dédupliquez les événements et validez l'horodatage signé selon votre politique de rejeu.
Renvoyer HTTP 200 OK sous 5 000 ms pour accuser réception
Découverte de la clé publique
GET /api/v1/webhooks/public-key renvoie la clé publique active pour la vérification des signatures
POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsClé API
Aperçu et points de terminaison
Créer un abonnement webhook
Enregistrer un point de terminaison HTTPS pour recevoir en temps réel les notifications d'événements signées HMAC (émission, mise à jour, scan, désinstallation).
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 l'URL HTTPS cible et le tableau d'événements types d'événements webhook.
Corps de la requête2 requis • 5 optionnel(s)
urlstring (HTTPS URL)
Requis
URL de votre serveur (doit commencer par https://, 2048 car. max).
Exemple : https://your-server.com/webhooks/passinstance
Fonctionnement et limites des Webhooks en mode Pull
Consommez les événements de cartes et de scans en temps réel via webhooks Push signés HMAC-SHA256 (avec backoff exponentiel et disjoncteur) ou via interrogation Pull Webhook pour environnements filtrés, ainsi que des Workflows sans code.
Résilience Push Webhook
5 tentatives avec backoff exponentiel avec gigue ; disjoncteur ouvert après 10 échecs consécutifs
Interrogation Pull Webhook
GET /api/v1/webhook-payload & POST /api/v1/webhook-payload/acknowledge pour réseaux privés