Skip to content
Référence API REST & SDKs

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.

Obtenir les clés API
Atelier docs en direct — les extraits se mettent à jour en temps réel
Aperçu

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.

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.

Clés de production (Live)
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Clés Sandbox (Test)
Authorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxx
Clés scanner matériel
x-scanner-key: scan_key_77a8b9c0d1e2f3a4...
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.

Ouvrir la spécification JSON OpenAPI 3.0
1. URL de spécification OpenAPI 3.0
https://passinstance.com/api/docs/openapi.json
2. Importer dans Postman / Bruno

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.

200 OK / 201 CreatedSuccès
{
  "success": true,
  "data": { ... },
  "errors": [],
  "statusCode": 200
}
Concepts clés

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).

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
Visuels Hero / BandeauApple : 375×123 px (3:1) | Google : 1032×336 px (env. 3:1)
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

Documentation complète Plateforme & API

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.

Ouvrir le Centre d'aide