# API Google Wallet

L'API Google Wallet vous permet de créer, mettre à jour, lister et gérer les [cartes Google Wallet](/fr/product/messaging-channels/google-wallet-passes/) par programmation. Elle prend en charge les mêmes opérations que le [générateur de cartes](/fr/product/messaging-channels/google-wallet-passes/pass-builder/) dans le Panneau de Contrôle.

Utilisez-la pour émettre des cartes de fidélité, des offres, des cartes-cadeaux, des billets d'événement, des cartes d'embarquement, des titres de transport et des cartes génériques, et pour envoyer des mises à jour en direct aux cartes déjà enregistrées sur les appareils de vos utilisateurs.

<Aside type="note" title="Prérequis : Configuration de Google Wallet">
Avant de pouvoir créer des cartes pour une application, un **ID d'émetteur** Google Wallet et une **clé de compte de service** doivent être configurés pour cette application dans le Panneau de Contrôle de Pushwoosh. Sans eux, les requêtes `create` et `update` échouent. Voir [Configuration des cartes Google Wallet pour Android](/fr/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-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, `serialNumber`, `hexBackgroundColor`, `logoUrl`).
*   **Champs non renseignés :** les réponses incluent tous les champs, même lorsqu'ils sont vides ou nuls.
*   **Identité :** le `serialNumber` est toujours attribué par le serveur lors de la création d'une carte. Toute valeur que vous envoyez lors de la création est ignorée. L'ID d'objet complet de Google Wallet est `{issuerId}.{serialNumber}`.
*   **Images :** `logoUrl` et `heroImageUrl` sont des URL HTTPS publiques vers des images que Google récupère — ce ne sont pas des fichiers téléversés.
*   **Style de carte :** un seul objet de style (`generic`, `offer`, `loyalty`, `eventTicket`, `giftCard`, `flight` ou `transit`) doit être défini sur une carte. Le style ne peut pas être modifié après la création.

### Réponses d'erreur

| 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` | La carte, le modèle ou l'application n'a pas été trouvé(e). |
| `503 Service Unavailable` | Le service est à pleine capacité ou temporairement indisponible. |

## Points de terminaison

| Méthode | Chemin | Description |
| :---- | :---- | :---- |
| `POST` | `/api/google/pass/validate` | Valider une configuration de carte |
| `POST` | `/api/google/pass/create` | Créer un nouvel objet de carte et obtenir un lien d'enregistrement |
| `POST` | `/api/google/pass/update/{serialNumber}` | Mettre à jour une carte existante ; Google livre la modification |
| `GET` | `/api/google/pass/{applicationCode}/{serialNumber}/save-link` | Obtenir un lien d'enregistrement « Ajouter à Google Wallet » |
| `GET` | `/api/google/pass/{applicationCode}/{serialNumber}` | Obtenir une seule carte |
| `GET` | `/api/google/passes` | Lister toutes les cartes pour une application |
| `POST` | `/api/google/pass/{applicationCode}/{serialNumber}/state` | Activer ou invalider une carte |
| `DELETE` | `/api/google/pass/{applicationCode}/{serialNumber}` | Supprimer une carte |
| `GET` | `/api/google/config` | Obtenir la configuration Google Wallet de l'application |
| `GET` | `/api/google/templates` | Lister les modèles de cartes disponibles |
| `GET` | `/api/google/templates/{filename}` | Obtenir un seul modèle |

## Créer une carte

Crée la classe et l'objet de la carte dans Google Wallet, puis renvoie le numéro de série attribué par le serveur, l'ID d'objet complet et un lien d'enregistrement « Ajouter à Google Wallet ».

`POST` `/api/google/pass/create`

### Corps de la requête

| Paramètre | Type | Requis | Description |
| :---- | :---- | :---- | :---- |
| `pass` | object | Oui | L'[objet de carte](#pass-object) décrivant la carte. Un seul style doit être défini. |
| `userId` | string | Oui | L'[ID utilisateur Pushwoosh](/fr/developer/api-reference/api-identifiers/#user-id) auquel la carte est émise. |
| `applicationCode` | string | Oui | Le [code d'application Pushwoosh](/fr/developer/api-reference/api-identifiers/#application-code). |

##### Exemple de requête

```json
{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}
```

### Réponse

| Champ | Type | Description |
| :---- | :---- | :---- |
| `serialNumber` | string | Identité unique attribuée par le serveur à la carte créée. |
| `objectId` | string | ID d'objet complet de Google Wallet : `{issuerId}.{serialNumber}`. |
| `saveLink` | string | Lien « Ajouter à Google Wallet » : `https://pay.google.com/gp/v/save/{jwt}`. |
| `message` | string | Message de résultat. |

##### Exemple de réponse

```json
{
  "serialNumber": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "objectId": "XXXXXXXXXXXXXXX.XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "saveLink": "https://pay.google.com/gp/v/save/{jwt}",
  "message": "Pass created successfully"
}
```

## Valider une carte

Vérifie une configuration de carte par rapport aux exigences de Google sans la créer. Utile avant d'appeler la création.

`POST` `/api/google/pass/validate`

### Corps de la requête

| Paramètre | Type | Requis | Description |
| :---- | :---- | :---- | :---- |
| `pass` | object | Oui | L'[objet de carte](#pass-object) à valider. |

### Réponse

| Champ | Type | Description |
| :---- | :---- | :---- |
| `valid` | boolean | Indique si la carte passe la validation. |
| `errors` | array of strings | Problèmes bloquants qui doivent être corrigés. |
| `warnings` | array of strings | Avis non bloquants. |

## Mettre à jour une carte

Met à jour l'objet de la carte avec un nouveau contenu. Google livre ensuite la version mise à jour à chaque appareil qui a enregistré la carte. Envoie éventuellement une notification Android avec la mise à jour.

`POST` `/api/google/pass/update/{serialNumber}`

### Paramètres de chemin

| Paramètre | Type | Description |
| :---- | :---- | :---- |
| `serialNumber` | string | Le numéro de série renvoyé lors de la création de la carte. |

### Corps de la requête

| Paramètre | Type | Requis | Description |
| :---- | :---- | :---- | :---- |
| `updates` | object | Oui | L'[objet de carte](#pass-object) avec le nouveau contenu. Le style ne peut pas être modifié. |
| `applicationCode` | string | Oui | Le [code d'application Pushwoosh](/fr/developer/api-reference/api-identifiers/#application-code). |
| `notifyMessage` | string | Non | Lorsqu'il n'est pas vide, envoie une notification Android avec ce texte à tous ceux qui ont enregistré la carte. Vide signifie une mise à jour silencieuse. |
| `notifyOnUpdate` | boolean | Non | Demander une notification de mise à jour de champ. Seules les cartes `loyalty`, `eventTicket` et `flight` notifient réellement ; les autres styles acceptent l'indicateur mais n'en envoient jamais. Les notifications ne se déclenchent que dans les 3 heures précédant une heure de début pertinente, et Google les limite à 3 notifications par carte par 24 heures. |

<Aside type="note" title="Deux façons de notifier lors d'une mise à jour">
`notifyMessage` envoie une notification Android personnalisée à tous ceux qui ont enregistré la carte et fonctionne pour n'importe quel style de carte. `notifyOnUpdate` demande à Google d'envoyer sa propre notification de mise à jour de champ, qui ne se déclenche que pour les cartes `loyalty`, `eventTicket` et `flight`.
</Aside>

### Réponse

| Champ | Type | Description |
| :---- | :---- | :---- |
| `success` | boolean | Indique si la mise à jour a réussi. |
| `message` | string | Message de résultat. |

## Obtenir un lien d'enregistrement

Renvoie un lien d'enregistrement « Ajouter à Google Wallet » pour une carte déjà créée. L'objet de la carte doit déjà exister (créé via [Créer une carte](#create-a-pass)).

`GET` `/api/google/pass/{applicationCode}/{serialNumber}/save-link`

### Réponse

| Champ | Type | Description |
| :---- | :---- | :---- |
| `saveLink` | string | `https://pay.google.com/gp/v/save/{jwt}`. |

<Aside type="tip" title="Partagez le lien ou affichez-le sous forme de code QR">
Placez le `saveLink` derrière un bouton « Ajouter à Google Wallet », ou affichez-le sous forme de code QR avec n'importe quelle bibliothèque QR. Lorsqu'un utilisateur l'ouvre, Google l'invite à enregistrer la carte et enregistre son appareil pour les mises à jour.
</Aside>

## Obtenir une carte

Renvoie une seule carte stockée, y compris son objet de carte complet.

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

### Réponse

Renvoie `{ "pass": { ... } }`, un seul [enregistrement de carte](#pass-record-object).

## Lister les cartes

Renvoie une liste paginée et triée des cartes stockées pour une application.

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

### Paramètres de requête

| Paramètre | Type | Requis | Description |
| :---- | :---- | :---- | :---- |
| `applicationCode` | string | Oui | Le [code d'application Pushwoosh](/fr/developer/api-reference/api-identifiers/#application-code). |
| `orderBy` | string | Non | Champ de tri : `UPDATED` (par défaut) ou `CREATED`. |
| `orderDirection` | string | Non | Sens de tri : `DESC` (par défaut, le plus récent en premier) ou `ASC`. |
| `page` | integer | Non | Index de page basé sur zéro. La valeur par défaut est `0`. |
| `perPage` | integer | Non | Taille de la page. `0` ou omis utilise la valeur par défaut du serveur. |

### Réponse

| Champ | Type | Description |
| :---- | :---- | :---- |
| `passes` | array of objects | La page actuelle des [enregistrements de carte](#pass-record-object). |
| `page` | integer | L'index de la page renvoyée. |
| `perPage` | integer | La taille de la page utilisée pour cette réponse. |
| `total` | integer | Nombre total de cartes pour l'application sur toutes les pages. |

## Définir l'état de la carte

Active ou invalide une carte. Une carte invalidée (inactive) est déplacée vers la section **Cartes expirées** de l'utilisateur dans Google Wallet ; l'enregistrement est conservé afin qu'elle puisse être réactivée.

`POST` `/api/google/pass/{applicationCode}/{serialNumber}/state`

### Corps de la requête

| Paramètre | Type | Requis | Description |
| :---- | :---- | :---- | :---- |
| `active` | boolean | Oui | `true` définit la carte sur `ACTIVE` ; `false` l'invalide (`INACTIVE`). |

### Réponse

Renvoie un objet vide `{}` en cas de succès.

## Supprimer une carte

Invalide la carte dans Google et supprime son enregistrement stocké dans Pushwoosh.

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

<Aside type="caution" title="Une carte enregistrée ne peut pas être supprimée de force">
Google ne permet pas de supprimer une carte déjà enregistrée sur l'appareil d'un utilisateur. La suppression invalide la carte (elle est déplacée vers les **Cartes expirées**) et supprime l'enregistrement Pushwoosh.
</Aside>

### Réponse

Renvoie un objet vide `{}` en cas de succès.

## Obtenir la configuration

Renvoie l'état de la configuration de Google Wallet pour une application.

`GET` `/api/google/config?applicationCode=XXXXX-XXXXX`

### Réponse

| Champ | Type | Description |
| :---- | :---- | :---- |
| `hasServiceAccount` | boolean | Indique si une clé de compte de service est configurée. |
| `issuerId` | string | L'[ID d'émetteur de la Google Pay & Wallet Console](/fr/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/#create-the-issuer-account) configuré. |
| `serviceAccountEmail` | string | Le `client_email` du [compte de service](/fr/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/#create-the-service-account-key) configuré. |

## Modèles

Listez les modèles de cartes d'exemple disponibles, ou récupérez-en un en tant qu'[objet de carte](#pass-object) que vous pouvez utiliser comme point de départ.

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

`GET` `/api/google/templates/{filename}` — renvoie `{ "template": { ...objet de carte... } }`.

## Référence d'objet

### Objet de carte

| Champ | Type | Description |
| :---- | :---- | :---- |
| `serialNumber` | string | Attribué par le serveur lors de la création ; identifie la carte. |
| `generic` / `offer` / `loyalty` / `eventTicket` / `giftCard` / `flight` / `transit` | object | Le style de la carte. **Un seul** doit être défini. Voir les objets de style ci-dessous. |
| `hexBackgroundColor` | string | Couleur de fond de la carte, `#rrggbb`. |
| `logoUrl` | string | URL HTTPS publique de l'image du logo. Requis pour les cartes de fidélité et de transport. |
| `heroImageUrl` | string | URL HTTPS publique d'une large image de bannière. |
| `barcode` | object | [Code-barres](#barcode-object) affiché sur la carte. |
| `textModules` | array | [Modules de texte](#text-module-object) affichés dans la vue détaillée. |
| `links` | array | [Modules de lien](#link-module-object) affichés dans la vue détaillée. |
| `expirationTime` | string | Heure ISO 8601 à laquelle Google fait expirer automatiquement la carte. Vide signifie pas d'expiration. |
| `appLink` | object | [Lien d'application](#app-link-object) : un bouton CTA au recto de la carte. |
| `locations` | array | [Lieux](#location-object) qui déclenchent une notification géolocalisée (max 10). |
| `holdersPolicy` | string | Qui peut enregistrer la carte : `ONE_USER_ALL_DEVICES` (par défaut), `ONE_USER_ONE_DEVICE`, ou `MULTIPLE_HOLDERS`. |

### Objet générique

| Champ | Type | Description |
| :---- | :---- | :---- |
| `cardTitle` | string | Requis. Le nom de l'émetteur/programme en haut de la carte. |
| `header` | string | Requis. Le titre principal de la carte. |
| `subheader` | string | Titre secondaire. |
| `cardFields` | array | Jusqu'à 6 [modules de texte](#text-module-object) épinglés au recto (jusqu'à 3 rangées de 2). |

### Objet d'offre

| Champ | Type | Description |
| :---- | :---- | :---- |
| `title` | string | Requis. Par exemple, `20 % de réduction sur tout`. |
| `provider` | string | Requis. Le nom du commerçant. |
| `details` | string | Détails de l'offre. |
| `finePrint` | string | Termes et conditions. |
| `redemptionChannel` | string | `ONLINE`, `INSTORE`, `BOTH` (par défaut), ou `TEMPORARY_PRICE_REDUCTION`. |
| `issuerName` | string | Affiché sur les surfaces « émis par » de Google ; la valeur par défaut est `provider`. |

### Objet de fidélité

| Champ | Type | Description |
| :---- | :---- | :---- |
| `programName` | string | Requis. Nécessite `logoUrl` sur la carte. |
| `accountName` | string | Nom du membre affiché sur la carte. |
| `accountId` | string | ID du membre affiché sur la carte. |
| `pointsLabel` | string | Par exemple, `Points`. Affiché uniquement avec un solde. |
| `pointsBalance` | string | Le solde de points. |
| `rewardsTier` | string | Par exemple, `Or`. |
| `rewardsTierLabel` | string | Étiquette à côté du niveau ; la valeur par défaut est `Niveau`. |
| `issuerName` | string | La valeur par défaut est `programName`. |

### Objet de billet d'événement

| Champ | Type | Description |
| :---- | :---- | :---- |
| `eventName` | string | Requis. |
| `venueName` / `venueAddress` | string | Détails du lieu. |
| `startDateTime` / `endDateTime` | string | ISO 8601 avec décalage (par exemple, `2026-07-01T19:30:00+02:00`). |
| `ticketHolderName` / `ticketNumber` / `ticketType` | string | Détails du détenteur et du billet. |
| `section` / `row` / `seat` / `gate` | string | Détails des places. |
| `issuerName` | string | La valeur par défaut est `eventName`. |

### Objet de carte-cadeau

| Champ | Type | Description |
| :---- | :---- | :---- |
| `merchantName` | string | Requis. |
| `cardNumber` | string | Requis. |
| `pin` | string | PIN de la carte. |
| `balance` | string | Montant décimal, par exemple `25.00`. Nécessite `balanceCurrency`. |
| `balanceCurrency` | string | Code de devise ISO 4217, par exemple `USD`. |
| `issuerName` | string | La valeur par défaut est `merchantName`. |

### Objet de vol

| Champ | Type | Description |
| :---- | :---- | :---- |
| `carrierIataCode` | string | Requis. Code IATA à 2 lettres, par exemple `LX`. |
| `airlineName` | string | Nom d'affichage de la compagnie aérienne. |
| `flightNumber` | string | Requis. Chiffres uniquement, par exemple `113`. |
| `originAirportCode` / `destinationAirportCode` | string | Requis. Codes IATA à 3 lettres. |
| `originTerminal` / `originGate` / `destinationTerminal` | string | Détails du terminal et de la porte. |
| `departureDateTime` | string | Requis. Heure **locale** de l'aéroport d'origine, ISO 8601 **sans** décalage (par exemple, `2026-09-01T06:30:00`). |
| `boardingTime` / `arrivalDateTime` | string | Même format local. `arrivalDateTime` est l'heure locale de destination. |
| `passengerName` | string | Requis. |
| `confirmationCode` / `seatNumber` / `seatClass` / `boardingGroup` | string | Détails du passager. |
| `issuerName` | string | La valeur par défaut est `airlineName`, puis le code du transporteur. |

### Objet de transport

| Champ | Type | Description |
| :---- | :---- | :---- |
| `transitType` | string | Requis. `BUS`, `RAIL`, `TRAM`, `FERRY`, ou `OTHER`. |
| `transitOperatorName` | string | Requis. Nécessite `logoUrl` sur la carte. |
| `passengerName` | string | Requis. |
| `ticketNumber` | string | Numéro de billet. |
| `tripType` | string | `ONE_WAY` (par défaut) ou `ROUND_TRIP`. |
| `legs` | array | Un ou plusieurs [tronçons de transport](#transit-leg-object) dans l'ordre du voyage. |
| `issuerName` | string | La valeur par défaut est `transitOperatorName`. |

### Objet de tronçon de transport

| Champ | Type | Description |
| :---- | :---- | :---- |
| `originName` / `destinationName` | string | Requis. |
| `departureDateTime` / `arrivalDateTime` | string | ISO 8601 ; décalage facultatif (heure locale si omis). |
| `platform` / `coach` / `seat` | string | Détails de l'embarquement. |
| `fareName` | string | Par exemple, `Billet Simple à Tout Moment`. |

### Objet de code-barres

| Champ | Type | Description |
| :---- | :---- | :---- |
| `format` | string | `QR_CODE`, `PDF_417`, `AZTEC`, `CODE_128`, `EAN_13`, et autres types de codes-barres Google Wallet. |
| `value` | string | Données encodées dans le code-barres. |
| `altText` | string | Texte affiché sous le code-barres. |

### Objet de module de texte

| Champ | Type | Description |
| :---- | :---- | :---- |
| `id` | string | Identifiant du module. |
| `header` | string | Titre du module. |
| `body` | string | Texte du module. |

### Objet de module de lien

| Champ | Type | Description |
| :---- | :---- | :---- |
| `uri` | string | URL du lien externe. |
| `description` | string | Étiquette du lien affichée dans la vue détaillée. |

### Objet de lien d'application

| Champ | Type | Description |
| :---- | :---- | :---- |
| `uri` | string | URL Web ou URI cible de lien profond. |
| `androidPackageName` | string | Facultatif. S'il est défini, ouvre l'application Android. |
| `description` | string | Description interne de l'URI cible (pas une étiquette de bouton visible) ; la valeur par défaut est l'URI. |

### Objet de lieu

| Champ | Type | Description |
| :---- | :---- | :---- |
| `latitude` | number | `-90.0` à `+90.0`. |
| `longitude` | number | `-180.0` à `+180.0`. |

### Objet d'enregistrement de carte

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

| Champ | Type | Description |
| :---- | :---- | :---- |
| `serialNumber` | string | Numéro de série de la carte. |
| `objectId` | string | ID d'objet complet de Google Wallet `{issuerId}.{serialNumber}`. |
| `cardTitle` | string | Titre/en-tête d'affichage pour la carte. |
| `header` | string | Titre d'affichage secondaire. |
| `userId` | string | [ID utilisateur Pushwoosh](/fr/developer/api-reference/api-identifiers/#user-id) auquel la carte a été émise. |
| `createdAt` / `updatedAt` | string | Horodatages de création et de dernière mise à jour. |
| `state` | string | `ACTIVE` ou `INACTIVE`. |
| `style` | string | `generic`, `offer`, `loyalty`, `eventTicket`, `giftCard`, `flight`, ou `transit`. |
| `pass` | object | L'objet de carte complet, pour l'édition. |