Documentation Développeur Passinstance
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.
Introduction — Aperçu de l'API
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.
https://api.passinstance.com/api/v1https://staging-api.passinstance.com/api/v1Authentification — 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.
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxxAuthorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxxx-scanner-key: scan_key_77a8b9c0d1e2f3a4...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.
export PASSINSTANCE_API_KEY="pi_test_..."POST /api/v1/passes avec templateId et serialNumber
Extraire response.data.passAccessUrl de la réponse 201 Created
Envoyer l'URL par SMS/e-mail ; l'utilisateur appuie sur « Ajouter à Apple/Google Wallet »
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.
https://passinstance.com/api/docs/openapi.jsonCliquez sur Importer dans Postman, Insomnia ou Bruno et collez /api/docs/openapi.json pour charger toutes les routes
Définissez baseUrl = https://api.passinstance.com et PASSINSTANCE_API_KEY = pi_test_...
Exécutez GET /api/v1/templates avec X-API-Key: pour tester votre espace de travail
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.
{
"success": true,
"data": { ... },
"errors": [],
"statusCode": 200
}Architecture & cycle de vie des cartes
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).
POST /api/v1/templatesMise en page maître, type de code-barres, couleurs de marque et champs de schéma
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.
Signature cryptographique PKCS#7 via certificat Apple Pass Type ID
Charge utile REST JWT via compte de service Google Cloud
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_PROGRAMLOYALTY_PROGRAM & Paliers
Cumul de points par scan (defaultChangeValue) avec progression automatique de palier
STAMP_CARDSTAMP_CARD_ADD / DEDUCT
Suit le nombre de tampons (0..maximumValue) avec onCap ('noop' | 'reset') et rewardClaimBehavior
PREPAID_CARDGrand livre PREPAID_CARD
Comptabilité de grand livre prépayé en sous-unités ISO 4217 avec application de disallowNegativeBalance
VALID_ONCE_PER_DAYVALID_ONCE_PER_DAY & RENEW
Limites de passage quotidiennes par fuseau horaire et prolongation automatique d'expirationDate au scan
Centre d'aide Passinstance : Parcourir les 10 domaines et 94 guides
Explorez les guides étape par étape, les schémas d'architecture des workflows, les modèles JSON et les ressources de dépannage pour chaque domaine.
Tout le nécessaire pour bien démarrer avec Passinstance.
Découvrez comment utiliser les cartes Wallet selon vos objectifs métier.
Concevez, émettez, organisez et maintenez vos cartes numériques.
Distribuez vos cartes et tenez les portefeuilles clients à jour.
Configurez les portefeuilles Apple/Google, certificats et fonctions NFC.
Validez les passes, gérez les entrées et traitez les récompenses.
Connectez Passinstance à vos outils existants et automatisez vos flux.
Suivez les performances, l'activité et l'adoption de vos cartes.
Gérez organisation, utilisateurs, abonnement et paramètres légaux.
Trouvez des réponses, débloquez un problème et contactez notre support.
