API Apple Wallet PassKit

L’API PassKit Designer vous permet de créer, mettre à jour, télécharger et gérer les passes Apple Wallet par programmation. Elle prend en charge les mêmes opérations que le constructeur de passes dans le Panneau de Configuration. Utilisez-la pour émettre des cartes de fidélité, des coupons, des billets d’événement, des cartes d’embarquement et des cartes de magasin, et pour envoyer des mises à jour en direct aux passes déjà installés sur les appareils de vos utilisateurs.

Prérequis : Certificat PassKit

Avant de pouvoir créer des passes pour une application, un certificat de signature iOS PassKit doit être configuré pour cette application. Le certificat est géré dans le Panneau de Configuration de Pushwoosh. Sans lui, les requêtes create et update échouent. Voir Configuration des passes Apple Wallet pour iOS.

URL de base

https://apple-passkit.svc-nue.pushwoosh.com

Tous les points de terminaison sont servis via HTTPS. Les requêtes et les réponses utilisent application/json sauf indication contraire.

Authentification

Chaque requête doit inclure un en-tête Authorization avec votre jeton d’accès à l’API Pushwoosh :

Authorization: Token <api-token>

Le compte propriétaire du jeton doit être propriétaire de l’application référencée par applicationCode. Une requête pour une application appartenant à un autre compte renvoie 403 Forbidden.

Conventions

• Nommage des champs : Les champs JSON utilisent le lowerCamelCase (par exemple, passTypeIdentifier, serialNumber, backgroundColor).
• Champs non remplis : les réponses incluent tous les champs, même lorsqu’ils sont vides ou nuls.
• Données binaires : les champs bytes tels que pkpassData et l’image data sont des chaînes encodées en Base64 en JSON.
• Numéros de série : le serialNumber est toujours attribué par le serveur lors de la création d’un pass. Toute valeur que vous envoyez à la création est ignorée ; il identifie le pass pour toutes les opérations ultérieures.

Réponses d’erreur

L’API mappe les codes de statut internes aux codes de statut HTTP :

Statut HTTP	Signification
400 Bad Request	Argument invalide — un champ obligatoire est manquant ou malformé.
401 Unauthorized	En-tête Authorization manquant ou invalide.
403 Forbidden	L’application n’appartient pas au compte de l’appelant.
404 Not Found	Le pass, le modèle ou l’application n’a pas été trouvé.
503 Service Unavailable	Le service est à pleine capacité ou temporairement indisponible.

Points de terminaison

Méthode	Chemin	Description
POST	/api/pass/validate	Valider une configuration de pass
POST	/api/pass/create	Créer un nouveau .pkpass
POST	/api/pass/update/{serialNumber}	Mettre à jour un pass existant et notifier les appareils
GET	/api/passes	Lister tous les passes pour une application
GET	/api/pass/{applicationCode}/{serialNumber}	Obtenir un seul pass
GET	/api/pass/{applicationCode}/{serialNumber}/download	Télécharger le .pkpass d’un pass existant
DELETE	/api/pass/{applicationCode}/{serialNumber}	Supprimer un pass
GET	/api/pass/{serialNumber}/registrations	Lister les appareils enregistrés pour un pass
GET	/api/config	Obtenir la configuration PassKit de l’application
GET	/api/templates	Lister les modèles de passes disponibles
GET	/api/templates/{filename}	Obtenir un seul modèle

Créer un pass

Génère, signe et stocke un nouveau pass, puis renvoie son numéro de série attribué par le serveur.

POST /api/pass/create

Conseil

Pour obtenir le fichier .pkpass lui-même, appelez Télécharger un pass (ou créez un lien d’installation / code QR) avec le numéro de série retourné.

Corps de la requête

Paramètre	Type	Requis	Description
pass	objet	Oui	L’objet pass décrivant le pass.
images	tableau d’objets	Non	Images du pass (icône, logo, etc.). icon et logo sont requis pour un pass valide.
userId	chaîne	Oui	L’ID utilisateur Pushwoosh auquel le pass est émis.
applicationCode	chaîne	Oui	Le code d’application Pushwoosh.

Note

Lors de la création, si teamIdentifier, passTypeIdentifier ou organizationName sont omis, ils prennent par défaut les valeurs du certificat configuré de l’application. formatVersion est par défaut 1. Le serialNumber est attribué côté serveur.

Exemple de requête

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

Réponse

Champ	Type	Description
serialNumber	chaîne	Identité unique attribuée par le serveur du pass créé. Utilisez-la pour récupérer le pass (Obtenir un pass) ou télécharger le .pkpass (Télécharger un pass).
message	chaîne	Message de résultat.

Exemple de réponse

{
  "serialNumber": "a1b2c3d4-1234-5678-9abc-def012345678",
  "message": "Pass created successfully"
}

Valider un pass

Vérifie une configuration de pass par rapport aux spécifications d’Apple sans créer de fichier. Utile avant d’appeler la création.

POST /api/pass/validate

Corps de la requête

Paramètre	Type	Requis	Description
pass	objet	Oui	L’objet pass à valider.

Réponse

Champ	Type	Description
valid	booléen	Indique si le pass passe la validation.
errors	tableau de chaînes	Problèmes bloquants qui doivent être corrigés.
warnings	tableau de chaînes	Avis non bloquants.

Mettre à jour un pass

Régénère le pass avec un nouveau contenu, le re-signe, incrémente son tag de mise à jour et envoie une notification push silencieuse à chaque appareil qui a enregistré le pass. iOS récupère et installe ensuite la version mise à jour en arrière-plan.

POST /api/pass/update/{serialNumber}

Paramètres de chemin

Paramètre	Type	Description
serialNumber	chaîne	Le numéro de série retourné lors de la création du pass.

Corps de la requête

Paramètre	Type	Requis	Description
updates	objet	Oui	L’objet pass complet avec le nouveau contenu.
applicationCode	chaîne	Oui	Le code d’application Pushwoosh.

Le serialNumber (du chemin) et le jeton d’authentification du pass sont conservés par le serveur, peu importe ce que vous envoyez.

Réponse

Champ	Type	Description
success	booléen	Indique si la mise à jour a réussi.
updateTag	entier	Nouveau tag de mise à jour (un horodatage Unix).
message	chaîne	Message de résultat.

Lister les passes

Renvoie une liste paginée et triée des passes stockés pour une application.

GET /api/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20

Paramètres de requête

Paramètre	Type	Requis	Description
applicationCode	chaîne	Oui	Le code d’application Pushwoosh.
orderBy	chaîne	Non	Champ de tri : UPDATED (par défaut) ou CREATED.
orderDirection	chaîne	Non	Sens de tri : DESC (par défaut, le plus récent en premier) ou ASC.
page	entier	Non	Index de page basé sur zéro. Par défaut 0.
perPage	entier	Non	Taille de la page. 0 ou omis utilise la valeur par défaut du serveur.

Réponse

Champ	Type	Description
passes	tableau d’objets	La page actuelle des enregistrements de pass.
page	entier	L’index de la page retournée.
perPage	entier	La taille de page utilisée pour cette réponse.
total	entier	Nombre total de passes pour l’application sur toutes les pages.

Exemple de réponse

{
  "passes": [ /* pass records */ ],
  "page": 0,
  "perPage": 20,
  "total": 137
}

Obtenir un pass

Renvoie un seul pass stocké, y compris son objet pass complet.

GET /api/pass/{applicationCode}/{serialNumber}

Paramètres de chemin

Paramètre	Type	Description
applicationCode	chaîne	Le code d’application Pushwoosh.
serialNumber	chaîne	Le numéro de série du pass.

Réponse

Renvoie { "pass": { ... } }, un seul enregistrement de pass.

Télécharger un pass

Renvoie le fichier .pkpass stocké d’un pass existant.

GET /api/pass/{applicationCode}/{serialNumber}/download

Réponse

Champ	Type	Description
pkpassData	chaîne (Base64)	Le fichier .pkpass.
filename	chaîne	Nom de fichier suggéré.

Supprimer un pass

Supprime un enregistrement de pass et son fichier .pkpass stocké.

DELETE /api/pass/{applicationCode}/{serialNumber}

Réponse

Champ	Type	Description
success	booléen	Indique si le pass a été supprimé.
message	chaîne	Message de résultat.

Obtenir les enregistrements de pass

Liste les appareils qui ont ajouté le pass et sont enregistrés pour les mises à jour.

GET /api/pass/{serialNumber}/registrations?applicationCode=XXXXX-XXXXX

Réponse

Renvoie { "registrations": [ ... ] }, où chaque élément a :

Champ	Type	Description
deviceLibraryIdentifier	chaîne	Identifiant de la bibliothèque d’appareils Apple.
pushToken	chaîne	Le jeton push du pass pour l’appareil.

Obtenir la configuration

Renvoie la configuration PassKit résolue pour une application à partir de son certificat.

GET /api/config?applicationCode=XXXXX-XXXXX

Réponse

Champ	Type	Description
teamIdentifier	chaîne	ID d’équipe Apple du certificat.
passTypeIdentifier	chaîne	ID de type de pass du certificat.
organizationName	chaîne	Nom de l’organisation du certificat.
hasCertificate	booléen	Indique si un certificat est configuré.
webServiceUrl	chaîne	URL de base du service web de pass. Les clients construisent un lien d’installation en ajoutant /v1/passes/{passType}/{serial}?token={authToken}.

Modèles

Listez les modèles de passes disponibles, ou récupérez-en un en tant qu’objet pass que vous pouvez utiliser comme point de départ.

GET /api/templates — renvoie { "templates": [ { "filename", "name", "description", "style" } ] }.

GET /api/templates/{filename} — renvoie { "template": { ...objet pass... } }.

Partager un pass sous forme de code QR

Pour permettre aux utilisateurs d’ajouter un pass en scannant un code QR (ou en appuyant sur un lien), encodez l’URL d’installation du pass dans un code QR. L’URL est construite à partir des valeurs que vous récupérez déjà de l’API :

{webServiceUrl}/v1/passes/{passTypeIdentifier}/{serialNumber}?token={authenticationToken}

Partie de l’URL	Où l’obtenir
webServiceUrl	GET /api/config → webServiceUrl
passTypeIdentifier	enregistrement de pass → pass.passTypeIdentifier (de la liste/obtention)
serialNumber	enregistrement de pass → serialNumber
authenticationToken	enregistrement de pass → pass.authenticationToken

Exemple :

https://apple-passkit.svc-nue.pushwoosh.com/v1/passes/pass.com.acme.loyalty/a1b2c3d4-1234-5678-9abc-def012345678?token=AbC123XyZ

Générez cette URL sous forme de code QR avec n’importe quelle bibliothèque QR. Lorsqu’un utilisateur la scanne, son appareil ouvre le lien, télécharge le dernier .pkpass, et Wallet l’invite à l’ajouter, ce qui enregistre également l’appareil pour les mises à jour.

Référence d’objet

Objet Pass

Champ	Type	Description
formatVersion	entier	Version du format du pass. Par défaut 1.
passTypeIdentifier	chaîne	ID de type de pass Apple (pass.com.yourcompany.passtype). Par défaut à partir du certificat.
serialNumber	chaîne	Attribué par le serveur à la création ; identifie le pass.
teamIdentifier	chaîne	ID d’équipe Apple. Par défaut à partir du certificat.
organizationName	chaîne	Organisation affichée sur le pass. Par défaut à partir du certificat.
description	chaîne	Description lisible par l’homme (requise par Apple).
boardingPass / coupon / eventTicket / storeCard / generic	objet	Le style du pass. Exactement un doit être défini. Voir les groupes de champs.
backgroundColor	chaîne	Couleur de fond, rgb(r, g, b).
foregroundColor	chaîne	Couleur de premier plan (texte), rgb(r, g, b).
labelColor	chaîne	Couleur de l’étiquette du champ, rgb(r, g, b).
logoText	chaîne	Texte affiché à côté du logo.
suppressStripShine	booléen	Désactiver l’effet de brillance sur l’image de la bande.
barcodes	tableau	Codes-barres affichés sur le pass.
locations	tableau	Emplacements qui rendent le pass pertinent.
beacons	tableau	Balises qui rendent le pass pertinent.
relevantDate	chaîne	Date ISO 8601 à laquelle le pass devient pertinent.
maxDistance	entier	Distance maximale (mètres) pour la pertinence de l’emplacement.
expirationDate	chaîne	Date d’expiration ISO 8601.
voided	booléen	Marque le pass comme nul.
groupingIdentifier	chaîne	Regroupe les passes associés (billets d’événement/cartes d’embarquement).
userInfo	objet (map)	Données d’application clé/valeur arbitraires.

Note

authenticationToken et webServiceUrl sont gérés par le service et n’ont pas besoin d’être définis par les clients de l’API.

Objet groupe de champs

Chaque style de pass (boardingPass, coupon, eventTicket, storeCard, generic) regroupe les champs en zones :

Champ	Type	Description
headerFields	tableau	Affiché dans l’en-tête du pass (visible lorsqu’il est empilé dans Wallet).
primaryFields	tableau	Champs les plus importants.
secondaryFields	tableau	Sous les champs primaires.
auxiliaryFields	tableau	Champs supplémentaires sous les secondaires.
backFields	tableau	Affiché au dos du pass.

boardingPass a en plus transitType (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, ou PKTransitTypeGeneric).

Objet champ

Champ	Type	Description
key	chaîne	Clé de champ unique dans le pass.
label	chaîne	Étiquette du champ.
value	chaîne	Valeur du champ (texte ou nombre sous forme de chaîne).
changeMessage	chaîne	Message affiché lorsque la valeur change (utilisez %@ comme espace réservé).
textAlignment	chaîne	Valeur PKTextAlignment.
dateStyle / timeStyle	chaîne	PKDateStyle pour le formatage de la date/heure.
isRelative	booléen	Afficher la date par rapport à maintenant.
numberStyle	chaîne	PKNumberStyle pour le formatage des nombres.
currencyCode	chaîne	Code de devise ISO 4217.
dataDetectorTypes	tableau de chaînes	Détecteurs de données à appliquer à la valeur.

Objet code-barres

Champ	Type	Description
format	chaîne	PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec, ou PKBarcodeFormatCode128.
message	chaîne	Données encodées dans le code-barres.
messageEncoding	chaîne	Encodage du texte, généralement iso-8859-1.
altText	chaîne	Texte affiché sous le code-barres.

Objet emplacement

Champ	Type	Description
latitude	nombre	Latitude.
longitude	nombre	Longitude.
altitude	nombre	Altitude en mètres.
relevantText	chaîne	Texte affiché sur l’écran de verrouillage à proximité de cet emplacement.

Objet balise

Champ	Type	Description
proximityUuid	chaîne	UUID de proximité iBeacon.
major	entier	Valeur majeure.
minor	entier	Valeur mineure.
relevantText	chaîne	Texte affiché sur l’écran de verrouillage à proximité de cette balise.

Objet image de pass

Champ	Type	Description
imageType	chaîne	Un parmi icon, logo, strip, background, footer, thumbnail. icon et logo sont requis.
data	chaîne (Base64)	Octets de l’image.
contentType	chaîne	Type MIME, par exemple image/png.

Objet enregistrement de pass

Retourné par les points de terminaison de liste/obtention.

Champ	Type	Description
serialNumber	chaîne	Numéro de série du pass.
passTypeIdentifier	chaîne	ID de type de pass.
organizationName	chaîne	Nom de l’organisation.
description	chaîne	Description du pass.
createdAt	chaîne	Horodatage de création (RFC 3339).
updatedAt	chaîne	Horodatage de la dernière mise à jour (RFC 3339).
updateTag	entier	Tag de mise à jour actuel.
pass	objet	L’objet pass complet, pour l’édition.
userId	chaîne	ID utilisateur Pushwoosh auquel le pass a été émis.