# 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](/fr/product/messaging-channels/apple-wallet-passes/) 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.

<Aside type="note" title="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](/fr/developer/first-steps/connect-messaging-services/ios-configuration/ios-wallet-pass-configuration/).
</Aside>

## 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](/fr/developer/api-reference/api-access-token/) :

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

<Aside type="tip">
Pour obtenir le fichier `.pkpass` lui-même, appelez [Télécharger un pass](#download-a-pass) (ou créez un [lien d'installation / code QR](#share-a-pass-as-a-qr-code)) avec le numéro de série retourné.
</Aside>

### Corps de la requête

| Paramètre | Type | Requis | Description |
| :--- | :--- | :--- | :--- |
| `pass` | objet | Oui | L'[objet pass](#pass-object) décrivant le pass. |
| `images` | tableau d'objets | Non | [Images du pass](#pass-image-object) (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](/fr/developer/api-reference/api-identifiers/#application-code). |

<Aside type="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.
</Aside>

##### Exemple de requête

```json
{
  "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](#get-a-pass)) ou télécharger le `.pkpass` ([Télécharger un pass](#download-a-pass)). |
| `message` | chaîne | Message de résultat. |

##### Exemple de réponse

```json
{
  "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](#pass-object) à 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](#pass-object) 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](#pass-record-object). |
| `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

```json
{
  "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](#pass-record-object).

## 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](#pass-object) 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`](#get-configuration) → `webServiceUrl` |
| `passTypeIdentifier` | [enregistrement de pass](#pass-record-object) → `pass.passTypeIdentifier` (de la liste/obtention) |
| `serialNumber` | [enregistrement de pass](#pass-record-object) → `serialNumber` |
| `authenticationToken` | [enregistrement de pass](#pass-record-object) → `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](#field-group-object). |
| `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](#barcode-object) affichés sur le pass. |
| `locations` | tableau | [Emplacements](#location-object) qui rendent le pass pertinent. |
| `beacons` | tableau | [Balises](#beacon-object) 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. |

<Aside type="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.
</Aside>

### Objet groupe de champs

Chaque style de pass (`boardingPass`, `coupon`, `eventTicket`, `storeCard`, `generic`) regroupe les [champs](#field-object) 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](#pass-object) complet, pour l'édition. |
| `userId` | chaîne | ID utilisateur Pushwoosh auquel le pass a été émis. |