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
Démarrage rapide en 5 minObtenir la clé API

Créez votre première carte Wallet en moins de 5 minutes

Émettez, signez cryptographiquement et distribuez des cartes Apple Wallet (.pkpass) & Google Wallet via une simple requête REST.

Studio carte en direct — modifiez les champs pour mettre à jour le code et la carte
Génère Apple Wallet (.pkpass) & Google Wallet
Aperçu
ARAcme Rewards
Points
450
Membre
Jane Doe
Gold VIP
MEMBER-2024-8891
PKCS#7 · .pkpassHTTP 201
POST/api/v1/passes
curl --max-time 30 -X POST https://api.passinstance.com/api/v1/passes \
  -H "X-API-Key: $PASSINSTANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{
    "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b",
    "serialNumber": "MEMBER-2024-8891",
    "externalId": "CRM-CUST-99201",
    "name": "Acme VIP Customer Pass",
    "attributes": {
      "guestName": "Jane Doe",
      "tier": "Gold VIP",
      "points": "450"
    },
    "storedValue": "50.00",
    "organizationName": "Acme Rewards",
    "backgroundColor": "#1b2d3c",
    "foregroundColor": "#ffffff",
    "labelColor": "#7db4f0",
    "barcode": {
      "value": "PI-8891-JD-VIP",
      "alternativeText": "8891-VIP"
    },
    "images": {
      "icon": "https://assets.passinstance.com/media/icon.png",
      "logo": "https://assets.passinstance.com/media/logo.png",
      "strip": "https://assets.passinstance.com/media/strip.png"
    },
    "relevantDate": "2026-08-25T18:00:00.000Z"
  }'
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

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

Exemple : pi_live_98a7b6c5d4e3f2a1
Paramètres de requête3 optionnel(s)

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/templates/{id}Clé API
Gestion des modèles

Obtenir les détails du modèle

Récupérer la configuration complète d'un modèle de carte : couleurs, code-barres, champs de mise en page et règles mécaniques.

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

Identifiant unique du modèle.

Exemple : tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/templates/{id}/fieldsClé API
Gestion des modèles

Obtenir les champs du modèle

Récupérez les définitions de champs dynamiques et les clés de propriétés personnalisées pouvant être renseignées par carte pour un modèle donné.

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 unique du modèle.

Exemple : 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Paramètres de requête1 optionnel(s)

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/templatesClé API
Gestion des modèles

Créer un modèle de carte

Concevoir et enregistrer un modèle réutilisable avec identité visuelle, type de code-barres, configuration NFC et champs de mise en page.

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

Configuration de création de modèle conforme au schéma JSON OpenAPI.

Corps de la requête6 requis • 4 optionnel(s)
namestring
Requis

Nom d'affichage du modèle.

Exemple : VIP Loyalty Card Template
descriptionstring
Requis

Description détaillée de l'usage de la carte et des avantages.

Exemple : Exclusive loyalty and rewards card for VIP customers
organizationNamestring
Requis

Nom de l'organisation ou marque affiché en haut de la carte.

Exemple : Acme Rewards
kindstring (enum)
Requis

storeCard, coupon, eventTicket, generic, boardingPass ou membership.

Exemple : storeCard
statusstring (enum)
Requis

DRAFT, PUBLISHED, ARCHIVED, DEPRECATED ou UNDER_REVIEW.

Exemple : PUBLISHED
preferredStyleSchemestring (enum)
Requis

DARK, posterGeneric, posterEventTicket, bannerEventTicket ou semanticBoardingPass.

Exemple : DARK

Codes de statut de réponse

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.

Corps de la requête4 optionnel(s)

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/templates/{id}/copyClé API
Gestion des modèles

Dupliquer le modèle

Dupliquez un modèle de carte existant avec sa mise en page, ses couleurs, ses images et ses mécaniques dans le même espace de travail.

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 source à dupliquer.

Exemple : 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Optional name, description, and ISO 4217 currency override for the duplicated template.

Corps de la requête3 optionnel(s)

Codes de statut de réponse

DELETEhttps://api.passinstance.com/api/v1/templates/{id}Clé API
Gestion des modèles

Supprimer le modèle

Supprimez un modèle de carte et planifiez une tâche asynchrone pour révoquer et désactiver les cartes associées dans Apple Wallet et Google Wallet.

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 à supprimer.

Exemple : 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Codes de statut de réponse

Notifications de modèle

3 points de terminaison
POSThttps://api.passinstance.com/api/v1/push-notifications/templates/{id}/sendClé API
Notifications de modèle

Diffuser un push aux cartes d'un modèle

Diffuser une notification push immédiate sur écran verrouillé à toutes les cartes actives Apple Wallet et Google Wallet émises sous un modèle.

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 dont les appareils enregistrés recevront la diffusion.

Exemple : tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Charge utile Charge utile de requête contenant pushNotificationText (85 car. max) et un texte d'en-tête optionnel.

Corps de la requête1 requis • 1 optionnel(s)
pushNotificationTextstring
Requis

Message sur écran verrouillé diffusé aux cartes actives du modèle (85 car. max ; prend en charge les variables).

Exemple : Flash Sale starts now! Show your VIP pass at checkout for 2x points.

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/templates/{id}/notificationClé API
Notifications de modèle

Lister les notifications planifiées

Listez toutes les campagnes de notifications push planifiées et récemment exécutées pour un modèle de carte spécifique.

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

Template UUID.

Exemple : 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Codes de statut de réponse

DELETEhttps://api.passinstance.com/api/v1/templates/notification/{notificationId}Clé API
Notifications de modèle

Annuler une notification planifiée

Annulez une notification push de modèle planifiée en attente avant sa diffusion aux appareils enregistrés.

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
notificationIdstring (UUID)
Requis

UUID de la notification planifiée renvoyé lors de la planification ou du listage.

Exemple : f1e2d3c4-b5a6-4987-8765-43210fedcba9

Codes de statut de réponse

Intégrations de modèle

2 points de terminaison
POSThttps://api.passinstance.com/api/v1/integration-connections/embed-widgetsClé API
Intégrations de modèle

Créer une intégration embarquée (iFrame)

Créez une configuration de widget iFrame intégrable pour un modèle publié afin d'embarquer l'inscription de cartes sur votre site web.

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

Configuration for the embedded download widget including templateId and allowed host domains.

Corps de la requête3 requis • 1 optionnel(s)
namestring
Requis

Nom d'affichage pour l'intégration du widget embarqué.

Exemple : Checkout Loyalty Embed Widget
templateIdstring (UUID)
Requis

UUID du modèle de carte cible.

Exemple : 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
allowedDomainsstring[]
Requis

Liste des origines (domaines) autorisées à intégrer le widget.

Exemple : ["shop.yourbrand.com", "app.yourbrand.com"]

Codes de statut de réponse

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

Codes de statut de réponse

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.

Exemple : CRM-CUST-99201

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/batch-pass-operations/createClé API
Gestion des cartes

Émettre des cartes en lot

Émettre plusieurs cartes wallet en une opération atomique par lot avec validation et rapport d'erreurs.

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 un tableau de configurations de cartes.

Corps de la requête1 requis
passesarray of objects
Requis

Tableau d'éléments de carte avec templateId, barcodeValue et additionalData.

Exemple : [ { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-001", "additionalData": { "name": "Member #001" } }, { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-002", "additionalData": { "name": "Member #002" } } ]

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/passesClé API
Gestion des cartes

Lister toutes les cartes

Récupérer une liste paginée de cartes pour l'espace client authentifié avec filtres de recherche et de statut.

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 requête13 optionnel(s)

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/passes/{id}Clé API
Gestion des cartes

Récupérer une carte

Obtenir tous les détails, le statut d'installation et les liens de téléchargement d'une carte par son ID unique.

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

Identifiant UUID unique de la carte.

Exemple : pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Codes de statut de réponse

PATCHhttps://api.passinstance.com/api/v1/passes/{id}Clé API
Gestion des cartes

Mettre à jour la carte et notifier

Mettre à jour les champs dynamiques, couleurs ou codes-barres et diffuser automatiquement des notifications push APNs et Google Wallet aux appareils.

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 unique de la carte à mettre à jour.

Exemple : pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Champs Charge utile de requête à modifier sur la carte. Les appareils installés reçoivent les mises à jour instantanément en arrière-plan.

Corps de la requête13 optionnel(s)

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/passes/voiding/{id}/voidClé API
Gestion des cartes

Désactiver une carte

Marquer une carte comme annulée ou réactivée dans Apple Wallet et Google Wallet avec propagation push instantanée.

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

ID unique de la carte à annuler ou réactiver.

Exemple : 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Charge utile Charge utile de requête contrôlant l'état d'annulation, le motif d'audit et les options de propagation wallet.

Corps de la requête1 requis • 1 optionnel(s)
voidedboolean
Requis

Définir à true pour annuler la carte, ou false pour la réactiver.

Exemple : true

Codes de statut de réponse

DELETEhttps://api.passinstance.com/api/v1/passes/{id}Clé API
Gestion des cartes

Supprimer la carte

Supprimez définitivement une carte de votre espace de travail et révoquez toute installation active dans Apple Wallet et Google Wallet.

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 unique de la carte à supprimer.

Exemple : b1d972dc-eccf-4f87-ab21-25939d9213d8

Codes de statut de réponse

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.

Exemple : INCREMENT

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/passes/{id}/adjust-valueClé API
Gestion des cartes

Ajuster le solde d'une carte

Créditer (ajouter) ou débiter (déduire) manuellement le solde stocké ou les points d'une carte avec journalisation d'audit.

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 un ajustement atomique et évitant tout double crédit.

Exemple : 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Paramètres de chemin1 requis
idUUID
Requis

ID de l'instance de carte ciblée.

Exemple : 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Charge utile d'ajustement spécifiant l'opération CREDIT ou DEBIT, le montant et le motif.

Corps de la requête2 requis • 2 optionnel(s)
actionstring
Requis

Action de transaction : 'CREDIT' pour ajouter du solde, ou 'DEBIT' pour en déduire.

Exemple : CREDIT
amountstring
Requis

Montant numérique à créditer ou débiter en chaîne.

Exemple : 25.00

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/mechanics/redeemClé API
Gestion des cartes

Échanger une récompense mécanique

Échanger une récompense de fidélité ou de carte à tampons gagnée via sa mécanique de carte configurée avec protection d'idempotence.

En-têtes1 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

Requête d'échange spécifiant passId, mechanicId et optionnellement idempotencyKey.

Corps de la requête2 requis • 3 optionnel(s)
passIdstring (UUID)
Requis

UUID de la carte utilisant la récompense.

Exemple : pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
mechanicIdstring (UUID)
Requis

UUID de la règle de mécanique de carte attachée au modèle.

Exemple : mech_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

Codes de statut de réponse

Recherche et analytique

4 points de terminaison
GEThttps://api.passinstance.com/api/v1/passes/searchClé API
Recherche et analytique

Rechercher des cartes

Effectuez une recherche plein texte sur les cartes émises par numéro de série, identifiant externe, e-mail, titulaire ou attributs.

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 requête1 requis
querystring
Requis

Chaîne de recherche (jusqu'à 500 caractères).

Exemple : Jane Doe

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/passes/statistics/{templateId}Clé API
Recherche et analytique

Obtenir les statistiques des cartes

Obtenez les statistiques agrégées d'émission, d'activation, d'installation wallet et d'utilisation pour un modèle de carte donné.

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
templateIdstring (UUID)
Requis

UUID du modèle cible.

Exemple : 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Paramètres de requête2 optionnel(s)

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/passes/{id}/historyClé API
Recherche et analytique

Obtenir l'historique de statut de la carte

Récupérez l'historique chronologique d'audit des changements de statut, mises à jour de solde/points, scans et annulations d'une carte.

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

Pass UUID.

Exemple : b1d972dc-eccf-4f87-ab21-25939d9213d8
Paramètres de requête1 optionnel(s)

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/passes/exportClé API
Recherche et analytique

Exporter les cartes en CSV

Diffuser un flux d'export CSV UTF-8 (text/csv; charset=utf-8) des instances de cartes sélectionnées par 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

Charge utile de requête spécifiant de 1 à 2 000 UUID de cartes et le format d'export.

Corps de la requête2 requis
passIdsstring[] (UUID v4)
Requis

Tableau de 1 à 2 000 UUID de cartes à inclure dans l'export CSV.

Exemple : ["pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"]
formatstring (enum)
Requis

Format de sortie d'export ('csv').

Exemple : csv

Codes de statut de réponse

Distribution des cartes

4 points de terminaison
GEThttps://api.passinstance.com/api/v1/passes/{id}/urisClé API
Distribution des cartes

Obtenir les URL de ressources de la carte

Obtenez les URL directes de téléchargement et de distribution d'une carte : page PassFlow, .pkpass, JWT Google Wallet et code QR.

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

Pass UUID.

Exemple : b1d972dc-eccf-4f87-ab21-25939d9213d8

Codes de statut de réponse

GEThttps://api.passinstance.com/d/{slug}/infoPublic
Distribution des cartes

Obtenir la page de téléchargement personnalisée

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.

Exemple : acme-vip-2026
Paramètres de requête2 optionnel(s)

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/passes/{id}/enabledownloadClé API
Distribution des cartes

Activer le téléchargement de la carte

Réactivez ou déverrouillez le lien de téléchargement d'une carte lorsque le modèle bloque les téléchargements multiples.

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 de la carte dont le téléchargement doit être débloqué.

Exemple : b1d972dc-eccf-4f87-ab21-25939d9213d8

Optional timestamp specifying how long re-download remains unlocked.

Corps de la requête1 optionnel(s)

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/passes/{id}/send-emailClé API
Distribution des cartes

Envoyer la carte par e-mail

Envoyez un e-mail transactionnel au titulaire contenant le lien direct d'installation pour Apple Wallet et Google Wallet.

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 de la carte à envoyer par e-mail.

Exemple : b1d972dc-eccf-4f87-ab21-25939d9213d8

Recipient email address(es) and optional custom subject and message body.

Corps de la requête4 optionnel(s)

Codes de statut de réponse

Notifications push

2 points de terminaison
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.

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/passes/sendpushnotificationsClé API
Notifications push

Envoyer des notifications push groupées

Envoyez une notification push sur écran verrouillé simultanément à une liste ciblée d'identifiants de cartes via APNs et Google Wallet.

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

Target pass UUID array (up to 500 passes) and notification message text supporting {attribute} placeholders.

Corps de la requête2 requis
listOfPassesstring[] (UUID)
Requis

Tableau contenant de 1 à 500 UUID de cartes.

Exemple : ["b1d972dc-eccf-4f87-ab21-25939d9213d8"]
pushNotificationTextstring
Requis

Message de notification sur écran verrouillé (prend en charge les variables comme {holderName}).

Exemple : Hi {holderName}, you unlocked a new reward!

Codes de statut de réponse

Gestion des lots

4 points de terminaison
POSThttps://api.passinstance.com/api/v1/bundles/upsertClé API
Gestion des lots

Créer ou mettre à jour un lot de cartes

Créez ou mettez à jour un lot multi-cartes (.pkpasses) permettant aux utilisateurs d'installer plusieurs cartes liées en un seul geste.

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

Array of pass UUIDs (up to 10) and optional existing bundleId.

Corps de la requête1 requis • 1 optionnel(s)
passesstring[] (UUID)
Requis

Tableau de 1 à 10 UUID de cartes à regrouper dans le lot.

Exemple : ["b1d972dc-eccf-4f87-ab21-25939d9213d8", "c2e083ed-fddf-4a98-bc32-36040e0324e9"]

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/bundles/{id}/passesClé API
Gestion des lots

Lister les cartes du lot

Listez toutes les cartes individuelles actuellement associées à un lot de cartes, avec leur statut et numéro de série.

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 lot de cartes.

Exemple : e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b
Paramètres de requête3 optionnel(s)

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/bundles/{id}/voidClé API
Gestion des lots

Annuler les cartes du lot

Annulez ou réactivez toutes les cartes appartenant à un lot de cartes en une seule opération.

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 lot de cartes.

Exemple : e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Confirmation flag and optional audit reason for voiding all passes in the bundle.

Corps de la requête1 requis • 1 optionnel(s)
voidedboolean
Requis

Doit être défini sur true pour annuler toutes les cartes du lot.

Exemple : true

Codes de statut de réponse

DELETEhttps://api.passinstance.com/api/v1/bundles/{id}Clé API
Gestion des lots

Supprimer le lot de cartes

Supprimez un conteneur de lot de cartes de votre espace de travail.

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 lot de cartes à supprimer.

Exemple : e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Codes de statut de réponse

Sécurité

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

Pipeline à 14 règles

PassStatus → Expiration → TimeWindow → Geofencing → Mechanics → RateLimit → AntiReplay

Synchronisation hors ligne

GET /api/v1/scans/offline-dataset fournit des instantanés paginés par curseur pour terminaux hors ligne

Appairage de clé scanner

POST /api/v1/scanner-keys/from-link échange un jeton d'appairage + PIN contre une clé x-scanner-key

Configuration du scanner

3 points de terminaison
GEThttps://api.passinstance.com/api/v1/validation/configsClé API
Configuration du scanner

Lister les configurations de scanner

Listez tous les profils de configuration de scanner (application mobile, scanner web, TPV) et leurs permissions de modèles.

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 requête2 optionnel(s)

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/validation/configs/{id}Clé API
Configuration du scanner

Obtenir la configuration du scanner

Obtenez les détails d'une configuration de scanner spécifique, incluant les modèles autorisés, le message après scan et les règles.

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 de la configuration de scanner.

Exemple : 7a8b9c0d-1e2f-4a3b-8c9d-0e1f2a3b4c5d

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/validation/configsClé API
Configuration du scanner

Créer une configuration de scanner

Créez un nouveau profil de configuration de scanner avec modèles autorisés, action de scan par défaut et message de confirmation.

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

Scanner configuration profile name, allowed template UUIDs, scan mode, and optional cooldown window.

Corps de la requête2 requis • 2 optionnel(s)
namestring
Requis

Nom lisible pour la configuration du scanner.

Exemple : Main Entrance Gate Scanners
templateIdsstring[] (UUID)
Requis

UUID des modèles autorisés pour la validation sous ce profil.

Exemple : ["8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b"]

Codes de statut de réponse

Opérations de scan

4 points de terminaison
GEThttps://api.passinstance.com/api/v1/validation/scansClé API
Opérations de scan

Lister les enregistrements de scan

Consultez le journal d'audit paginé des scans de cartes avec filtrage par modèle, carte, configuration de scanner, décision et période.

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 requête3 optionnel(s)

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/scansClé Scanner
Opérations de scan

Traiter un scan code-barres / NFC

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.

Exemple : PI-8891-JD-VIP

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/scans/prepareClé Scanner
Opérations de scan

Préparer un nonce de scan anti-rejeu

Émettre un nonce cryptographique anti-rejeu éphémère lié à un code-barres de carte avant d'exécuter POST /api/v1/scans.

En-têtes1 requis
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

Charge utile de requête contenant la valeur du code-barres scanné à associer au nonce cryptographique.

Corps de la requête1 requis
scannedBarcodeValuestring
Requis

Chaîne de code-barres ou jeton NFC à associer au nonce anti-rejeu.

Exemple : PI-8891-JD-VIP

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/scans/offline-datasetClé Scanner
Opérations de scan

Télécharger le jeu de données scanner hors ligne

Télécharger un instantané paginé par curseur des cartes autorisées pour la clé x-scanner-key afin de permettre la validation locale hors ligne.

En-têtes1 requis
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
Paramètres de requête3 optionnel(s)

Codes de statut de réponse

Aperçu et points de terminaison

4 points de terminaison
Webhooks

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.

Événements pris en charge

PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED

Réponse attendue

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
eventsstring[] (enum)
Requis

Valeurs types d'événements webhook : PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED.

Exemple : ["PASS_CREATED", "PASS_UPDATED", "APP_SCAN_CREATED"]

Codes de statut de réponse

DELETEhttps://api.passinstance.com/api/v1/webhooks/subscriptions/{id}Clé API
Aperçu et points de terminaison

Se désabonner d'un Webhook

Supprimez un abonnement webhook actif via son identifiant et arrêtez l'envoi d'événements futurs vers cette URL.

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 de l'abonnement webhook à supprimer.

Exemple : 3fa85f64-5717-4562-b3fc-2c963f66afa6

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptionsClé API
Aperçu et points de terminaison

Lister les abonnements webhook

Récupérer tous les abonnements webhook actifs enregistrés pour votre espace client.

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

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/webhooks/public-keyPublic
Aperçu et points de terminaison

Obtenir la clé publique de signature Webhook

Récupérez la clé publique PEM active de Passinstance pour vérifier cryptographiquement les signatures des webhooks sortants.

Codes de statut de réponse

Webhooks en mode Pull

2 points de terminaison
Webhooks

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

Déclencheurs Workflow

PASS_CREATED, APP_SCAN_CREATED, PASS_INSTALLED, TIER_CHANGED, BALANCE_CHANGED, SCHEDULED

Actions Workflow

SEND_PUSH_NOTIFICATION, UPDATE_PASS_FIELDS, SEND_EMAIL, WEBHOOK, MOVE_TO_SEGMENT

GEThttps://api.passinstance.com/api/v1/webhook-payloadClé API
Webhooks en mode Pull

Interroger la file des événements pull-webhook

Récupérer les événements webhook en attente via HTTPS GET sortant pour les réseaux privés ou filtrés par pare-feu sans ouvrir de port entrant.

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 requête3 optionnel(s)

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/webhook-payload/acknowledgeClé API
Webhooks en mode Pull

Acquitter les événements pull-webhook

Acquitter les charges utiles pull-webhook traitées jusqu'à un ID donné pour les marquer livrées et les retirer de la file de scrutation.

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 spécifiant l'ID borne supérieure traité (upTo).

Corps de la requête1 requis • 1 optionnel(s)
upTostring (UUID)
Requis

Dernier ID de charge utile traité ; tous les événements jusqu'à cet ID sont acquittés.

Exemple : whp_55a4b3c2-1d0e-9f8a-7b6c-5d4e3f2a1b0c

Codes de statut de réponse

Événements Webhook

4 guides
Événements WebhookNotification Webhook HTTP POST sortante

Événements de modèle (Template Events)

Notifications webhook HTTP POST envoyées lorsqu'un modèle de carte est créé, modifié, publié ou supprimé.

Modèle créé
POST
TEMPLATE_CREATED

Émis lors de la création d'un nouveau modèle de carte

Modèle mis à jour
POST
TEMPLATE_UPDATED

Émis lors de la modification des champs, de la mise en page ou des mécaniques

Modèle publié
POST
TEMPLATE_PUBLISHED

Émis lors de la publication d'un brouillon vers les cartes actives

Modèle supprimé
POST
TEMPLATE_DELETED

Émis lors du lancement de la suppression du modèle et de la révocation wallet

Événements WebhookNotification Webhook HTTP POST sortante

Événements de carte (Pass Events)

Notifications webhook HTTP POST suivant chaque étape du cycle de vie d'une carte, de l'émission au retrait de l'appareil.

Carte créée
POST
PASS_CREATED

Émis immédiatement lorsqu'une nouvelle carte est créée via l'API REST ou PassFlow

Carte mise à jour
POST
PASS_UPDATED

Émis lorsque les attributs, points de fidélité, palier ou solde de la carte changent

Carte annulée
POST
PASS_VOIDED

Émis lorsqu'une carte est annulée ou désactivée dans Apple Wallet et Google Wallet

Premier téléchargement
POST
PASS_FIRST_DOWNLOAD

Émis la première fois qu'un client récupère ou télécharge la carte

Carte téléchargée
POST
PASS_DOWNLOADED

Émis lors de chaque téléchargement ultérieur du fichier ou lien Google Wallet

Carte retirée de l'appareil
POST
PASS_REMOVED

Émis lorsque le client supprime la carte d'Apple Wallet ou de Google Wallet

Événements WebhookNotification Webhook HTTP POST sortante

Événements de scan (Scan Events)

Notifications webhook HTTP POST émises en temps réel dès qu'un code-barres ou une carte NFC est scanné et validé.

Scan de carte créé
POST
APP_SCAN_CREATED

Émis lorsque POST /api/v1/scans ou un scanner appairé enregistre un scan

Métadonnées du scan

Inclut passId, serialNumber, templateId, configId, décision de validation et variation de solde

Garantie de livraison

Livraison HTTPS POST au moins une fois avec en-têtes X-Webhook-Id et X-Webhook-Signature

Compatibilité file Pull

Également disponible via GET /api/v1/webhook-payload pour les systèmes de caisse derrière pare-feu

Événements WebhookNotification Webhook HTTP POST sortante

Événements de message et référence des statuts (Message Events)

Notifications webhook HTTP POST et codes de statut de livraison pour les notifications push wallet, e-mails et SMS.

Message envoyé
POST
MESSAGE_SENTNOTIFICATION_SENT

Émis lors de l'envoi d'un message ou d'une notification push

Échec de livraison
POST
MESSAGE_FAILED

Émis lorsqu'un e-mail, SMS ou push sortant échoue à la livraison

Référence des statuts de message

QUEUED -> SENT -> DELIVERED (ou FAILED / BOUNCED avec code de diagnostic)

Corrélation idempotente

Associez eventId et passId dans votre consommateur webhook pour dédupliquer les renvois

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