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

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

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