Skip to content
Guide du centre d'aide · API développeur
6 min de lectureVérifié 2026-11-16

Référence API

Parcourez tous les endpoints REST pour Passes, Modèles, Scanner, Livraison, Webhooks et Opérations en lot.

Dans ce guide

Aperçu

L'API REST Passinstance est organisée en contrôleurs de domaines modulaires montés principalement sous /api/v1 (avec des points de montage dédiés sans préfixe pour la caisse POS /v1/pos/*, les Pull Webhooks /webhook-payload, les webhooks entrants fournisseurs /webhooks/*, les sondes de santé /health/* ainsi que les liens intelligents /s/:token et /d/:slug). Chaque point d'entrée utilise les verbes HTTP standard (GET, POST, PUT, PATCH, DELETE), applique l'isolation locataire de l'espace depuis votre identifiant API et retourne une charge utile JSON déterministe (API response (T) sur les API d'espace de travail).

Prérequis : Générez une clé API d'espace (pi_live_... ou pi_test_...) dotée des API_KEY_SCOPE_VALUES requis (passes, templates, scans, webhooks, analytics ou *) sous /settings/workspace/developer/api-credentials avant d'appeler les routes /api/v1/*. Une documentation OpenAPI interactive est accessible sur GET /api/public/docs et /docs.

Cycle de vie des requêtes & réponses

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
CYCLE DE REQUÊTE API REST & ENVELOPPE
ACTEURS SYSTÈME PARTICIPANTS
P1 Intégration externe
P2 Passinstance /api/v1/*
P3 Fournisseurs Wallet & BDD
ÉTAPE 1 REQUÊTE / ACTION POST/api/v1/passes
ÉTAPE 2 REQUÊTE / ACTION Valider DTO & locataire
ÉTAPE 3 REQUÊTE / ACTION Signer .pkpass (bundleId)
›
idempotencyKey
›
& générer JWT Google Wallet
ÉTAPE 4 RÉPONSE 201 Created
›
API response (request payload)
ÉTAPE 5 REQUÊTE / ACTION PATCH/api/v1/passes/:id
ÉTAPE 6 REQUÊTE / ACTION Enregistrer mise à jour
ÉTAPE 7 RÉPONSE 200 OK
›
7. Mettre en file Push APNs/Google

Catalogue des points d'entrée REST par domaine

1. Passes, Upserts & opérations en masse

VerbeCheminDescription
POST/api/v1/passesÉmet une instance de passe (request payload : templateId, externalId optionnel, idempotencyKey, attributes) signée avec le certificat du modèle (bundleId = passTypeIdentifier Apple).
POST/api/v1/passes/upsert-by-external-idCrée ou met à jour de façon idempotente un passe apparié sur (templateId, externalId) (request payload).
GET/api/v1/passesListe les instances de passes avec pagination, filtrage par statut (pass status) et recherche.
GET/api/v1/passes/:idRécupère tous les détails, attributs dynamiques, externalId, serialNumber et statut d'enregistrement.
PATCH / PUT/api/v1/passes/:idMet à jour les champs dynamiques, le palier ou la date d'expiration et pousse la mise à jour vers les portefeuilles installés.
POST/api/v1/passes/voiding/:id/voidInvalide un passe (request payload + VoidingReason) et envoie un push silencieux voided: true.
DELETE/api/v1/passes/:idSupprime logiquement un passe et révoque les installations wallet actives.
POST/api/v1/passes/exportExporte une liste filtrée d'enregistrements de passes en téléchargement CSV UTF-8 ou JSON.
POST/api/v1/batch-pass-operations/createExécute des créations en masse synchrones/en file via Batch Operations API (ainsi que /update, /upsert, /activate, /deactivate, /delete).
POST/api/v1/batch-processingSoumet un traitement asynchrone volumineux CSV/JSON suivi via Batch Processing API.

2. Modèles & mécaniques

VerbeCheminDescription
GET/api/v1/templatesListe les modèles de l'espace, leurs types (PassKind), liaisons de certificat bundleId et états de publication.
GET/api/v1/templates/:idRetourne le schéma du modèle, la configuration visuelle et les mécaniques actives.
POST/api/v1/templates/:id/publishPublie les modifications de brouillon (request payload) et diffuse les mises à jour push par lots (GET .../publish-risk-check au préalable).
GET/api/v1/templates/:templateId/attributesListe les clés de champs dynamiques et leurs types attendus à l'émission (prend en charge OAuth templates:read).
POST/api/v1/mechanics/redeemConsomme une récompense débloquée de fidélité ou carte à tampons (request payload : UUID passId, mechanicId).
GET/api/v1/mechanics/:mechanicId/passes/:passId/ledgerRetourne le grand livre des transactions de la mécanique prépayée ou fidélité d'un passe (GET /api/v1/balance-changes pour le flux global).

3. Scans, appareils & validation POS

VerbeCheminDescription
POST/api/v1/scansÉvalue un scan code-barres/NFC face au moteur à 14 règles Validation Rules Engine (ScanMode & scan status).
POST/api/v1/scans/prepareÉmet un jeton cryptographique éphémère scan nonce pour la protection anti-rejeu.
GET/api/v1/scans/passRecherche de passe en lecture seule par ?barcode=... (ou par paramètre de chemin GET /api/v1/scans/pass/:barcodeValue).
POST/api/v1/scans/pass/:passId/useExécute directement une action request payload (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET).
GET/api/v1/scans/result/:scanIdRécupère l'enregistrement d'audit et ruleTrace d'un scan effectué.
GET/api/v1/scans/offline-datasetInstantané paginé par curseur (offline scan dataset) pour scanners mobiles hors ligne.
POST/v1/pos/redeemPoint d'entrée POS sans préfixe exécutant des opérations PosOperation atomiques (DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID, CUSTOM).
POST/api/v1/reader/redeemTraite les validations depuis lecteurs NFC matériels authentifiés via X-Reader-Secret (POST /api/v1/reader/validate pour contrôle d'entrée).

4. Notifications push, webhooks & workflows

VerbeCheminDescription
POST/api/v1/push-notifications/templates/:id/sendEnvoie une notification immédiate à tous les appareils enregistrés sur un modèle (request payload sur /passes/:id/schedule).
POST/api/v1/push-notifications/segmentationCible un segment de passes filtré (request payload) avec des mises à jour push localisées.
POST/api/v1/push-notifications/batchEnvoie des notifications par lots sur des listes de passes ou imports CSV (request payload).
GET / POST/api/v1/webhooksConsulte l'état des webhooks ou gère les abonnements HTTPS sortants (/api/v1/webhooks/subscriptions).
GET/webhook-payloadAPI Pull sans préfixe (GET /api/v3/webhook-payload également supporté) pour interroger les événements en attente derrière un pare-feu.
POST/webhook-payload/acknowledgeAcquittement sans préfixe ({ upTo, webhookId }, ou POST /api/v3/webhook-payload/acknowledge).
GET / POST/api/v1/workflowsListe ou crée des workflows automatisés événementiels (Workflow Engine API, aux côtés de /api/v1/automations).

5. Analytique, facturation & gouvernance des données

VerbeCheminDescription
GET/api/v1/analyticsRapport multi-séries de télémétrie (passes, registrations, walletAppsShare ; voir /api/v1/analytics/passes/overview).
GET/api/v1/analytics/wallet-installationsMatrice des installations Apple Wallet vs Google Wallet par appareil et par passe (request payload).
GET/api/v1/billing/subscriptionRetourne la formule d'abonnement active, la périodicité et l'état de renouvellement.
GET/api/v1/billing/invoices/:id/downloadTransmet la facture fiscale PDF (application/pdf).
POST/api/v1/customer/:customerId/privacy-settings/data-subject-exportGénère une archive de données personnelles conforme au RGPD pour un titulaire de passe.

Enveloppe standard API response (T) & codes de statut

Enveloppe de succès (200 OK / 201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01hxyz8821",
    "templateId": "tmpl_vip_member",
    "serialNumber": "PI-VIP-8821",
    "externalId": "crm_cust_44910",
    "bundleId": "pass.com.passinstance.vip",
    "status": "ACTIVE",
    "passAccessUrl": "https://api.passinstance.com/s/vip-8821-x9a2"
  },
  "meta": {
    "requestId": "req_99481a2b7c",
    "timestamp": "2026-11-16T10:10:00.000Z"
  }
}

Codes de statut HTTP standard

Code de statutSignificationRésolution
200 OK / 201 CreatedRequête exécutée avec succès de manière synchrone.Lire la charge utile retournée dans data.
400 Bad RequestÉchec de validation DTO ou contrainte métier non respectée.Inspecter errorCode, messageKey et le tableau details.
401 UnauthorizedClé API ou jeton Bearer manquant, expiré ou invalide.Vérifier x-api-key ou Authorization (ainsi que la correspondance pi_test_ vs pi_live_).
403 ForbiddenLa clé valide ne dispose pas de la portée requise (ex. 'passes') ni de l'accès locataire.Contrôler les portées assignées via GET /api/v1/api-keys.
404 Not FoundL'identifiant ressource ciblé est introuvable dans l'espace authentifié.Vérifier l'UUID / serialNumber / externalId et l'environnement d'espace.
409 ConflictDoublon sur externalId, serialNumber ou collision d'idempotence concurrente.Utiliser /api/v1/passes/upsert-by-external-id ou fournir un idempotencyKey unique.
429 Too Many RequestsDépassement du plafond de requêtes par seconde ou de quota.Respecter les en-têtes Retry-After et RateLimit-Reset.

Parcourez les définitions complètes des schémas sur le Hub documentation développeur et dans Présentation API & authentification.

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.