# Google Wallet API

Google Wallet API позволяет программно создавать, обновлять, получать списки и управлять [картами Google Wallet](/ru/product/messaging-channels/google-wallet-passes/). Он поддерживает те же операции, что и [конструктор карт](/ru/product/messaging-channels/google-wallet-passes/pass-builder/) в Панели управления.

Используйте его для выпуска карт лояльности, предложений, подарочных карт, билетов на мероприятия, посадочных талонов на самолет, проездных билетов и универсальных карт, а также для отправки обновлений в реальном времени на карты, уже сохраненные на устройствах ваших пользователей.

<Aside type="note" title="Предварительное условие: конфигурация Google Wallet">
Прежде чем вы сможете создавать карты для приложения, для этого приложения в Панели управления Pushwoosh должны быть настроены **Issuer ID** и **ключ сервисного аккаунта** Google Wallet. Без них запросы `create` и `update` завершатся ошибкой. См. [Конфигурация карт Google Wallet для Android](/ru/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/).
</Aside>


## Базовый URL

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

Все эндпоинты обслуживаются по HTTPS. Запросы и ответы используют `application/json`, если не указано иное.

## Аутентификация

Каждый запрос должен включать заголовок `Authorization` с вашим [токеном доступа к API Pushwoosh](/ru/developer/api-reference/api-access-token/):

```
Authorization: Token <api-token>
```

Аккаунт, которому принадлежит токен, должен владеть приложением, на которое ссылается `applicationCode`. Запрос для приложения, принадлежащего другому аккаунту, вернет `403 Forbidden`.

## Соглашения

*   **Именование полей:** Поля JSON используют `lowerCamelCase` (например, `serialNumber`, `hexBackgroundColor`, `logoUrl`).
*   **Незаполненные поля:** ответы включают все поля, даже если они пустые или имеют нулевое значение.
*   **Идентификация:** `serialNumber` всегда присваивается сервером при создании карты. Любое значение, которое вы отправляете при создании, игнорируется. Полный идентификатор объекта Google Wallet — `{issuerId}.{serialNumber}`.
*   **Изображения:** `logoUrl` и `heroImageUrl` — это публичные HTTPS URL-адреса изображений, которые Google загружает, а не загруженные файлы.
*   **Стиль карты:** для карты должен быть установлен ровно один объект стиля (`generic`, `offer`, `loyalty`, `eventTicket`, `giftCard`, `flight` или `transit`). Стиль не может быть изменен после создания.

### Ответы об ошибках

| HTTP-статус | Значение |
| :---- | :---- |
| `400 Bad Request` | Неверный аргумент — обязательное поле отсутствует или имеет неверный формат. |
| `401 Unauthorized` | Отсутствует или недействителен заголовок `Authorization`. |
| `403 Forbidden` | Приложение не принадлежит аккаунту вызывающей стороны. |
| `404 Not Found` | Карта, шаблон или приложение не найдены. |
| `503 Service Unavailable` | Сервис перегружен или временно недоступен. |

## Эндпоинты

| Метод | Путь | Описание |
| :---- | :---- | :---- |
| `POST` | `/api/google/pass/validate` | Проверить конфигурацию карты |
| `POST` | `/api/google/pass/create` | Создать новый объект карты и получить ссылку для сохранения |
| `POST` | `/api/google/pass/update/{serialNumber}` | Обновить существующую карту; Google доставит изменение |
| `GET` | `/api/google/pass/{applicationCode}/{serialNumber}/save-link` | Получить ссылку для сохранения "Добавить в Google Wallet" |
| `GET` | `/api/google/pass/{applicationCode}/{serialNumber}` | Получить одну карту |
| `GET` | `/api/google/passes` | Получить список всех карт для приложения |
| `POST` | `/api/google/pass/{applicationCode}/{serialNumber}/state` | Активировать или сделать недействительной карту |
| `DELETE` | `/api/google/pass/{applicationCode}/{serialNumber}` | Удалить карту |
| `GET` | `/api/google/config` | Получить конфигурацию Google Wallet для приложения |
| `GET` | `/api/google/templates` | Получить список доступных шаблонов карт |
| `GET` | `/api/google/templates/{filename}` | Получить один шаблон |

## Создать карту

Создает класс и объект карты в Google Wallet, затем возвращает присвоенный сервером серийный номер, полный идентификатор объекта и ссылку для сохранения "Добавить в Google Wallet".

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

### Тело запроса

| Параметр | Тип | Обязательный | Описание |
| :---- | :---- | :---- | :---- |
| `pass` | object | Да | [Объект карты](#pass-object), описывающий карту. Должен быть установлен ровно один стиль. |
| `userId` | string | Да | [User ID Pushwoosh](/ru/developer/api-reference/api-identifiers/#user-id), которому выдана карта. |
| `applicationCode` | string | Да | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code). |

##### Пример запроса

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

### Ответ

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `serialNumber` | string | Уникальный идентификатор созданной карты, присвоенный сервером. |
| `objectId` | string | Полный идентификатор объекта Google Wallet: `{issuerId}.{serialNumber}`. |
| `saveLink` | string | Ссылка "Добавить в Google Wallet": `https://pay.google.com/gp/v/save/{jwt}`. |
| `message` | string | Сообщение о результате. |

##### Пример ответа

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

## Проверить карту

Проверяет конфигурацию карты на соответствие требованиям Google без ее создания. Полезно перед вызовом create.

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

### Тело запроса

| Параметр | Тип | Обязательный | Описание |
| :---- | :---- | :---- | :---- |
| `pass` | object | Да | [Объект карты](#pass-object) для проверки. |

### Ответ

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `valid` | boolean | Проходит ли карта проверку. |
| `errors` | array of strings | Блокирующие проблемы, которые необходимо исправить. |
| `warnings` | array of strings | Неблокирующие рекомендации. |

## Обновить карту

Обновляет объект карты новым содержимым. Затем Google доставляет обновленную версию на каждое устройство, сохранившее карту. Опционально отправляет уведомление на Android с обновлением.

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

### Параметры пути

| Параметр | Тип | Описание |
| :---- | :---- | :---- |
| `serialNumber` | string | Серийный номер, возвращенный при создании карты. |

### Тело запроса

| Параметр | Тип | Обязательный | Описание |
| :---- | :---- | :---- | :---- |
| `updates` | object | Да | [Объект карты](#pass-object) с новым содержимым. Стиль не может быть изменен. |
| `applicationCode` | string | Да | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code). |
| `notifyMessage` | string | Нет | Если не пусто, отправляет push-уведомление на Android с этим текстом всем, кто сохранил карту. Пустое значение означает тихое обновление. |
| `notifyOnUpdate` | boolean | Нет | Запросить уведомление об обновлении поля. Фактически уведомляют только карты `loyalty`, `eventTicket` и `flight`; другие стили принимают флаг, но никогда не отправляют уведомление. Уведомления срабатывают только в течение 3 часов до соответствующего времени начала, и Google ограничивает их до 3 уведомлений на карту в сутки. |

<Aside type="note" title="Два способа уведомить об обновлении">
`notifyMessage` отправляет кастомное уведомление на Android всем, кто сохранил карту, и работает для любого стиля карты. `notifyOnUpdate` просит Google отправить собственное уведомление об обновлении поля, которое срабатывает только для карт `loyalty`, `eventTicket` и `flight`.
</Aside>

### Ответ

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `success` | boolean | Успешно ли прошло обновление. |
| `message` | string | Сообщение о результате. |

## Получить ссылку для сохранения

Возвращает ссылку "Добавить в Google Wallet" для уже созданной карты. Объект карты должен уже существовать (создан через [Создать карту](#create-a-pass)).

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

### Ответ

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `saveLink` | string | `https://pay.google.com/gp/v/save/{jwt}`. |

<Aside type="tip" title="Поделитесь ссылкой или отобразите ее в виде QR-кода">
Разместите `saveLink` за кнопкой "Добавить в Google Wallet" или отобразите ее в виде QR-кода с помощью любой QR-библиотеки. Когда пользователь откроет ее, Google предложит сохранить карту и зарегистрирует его устройство для получения обновлений.
</Aside>

## Получить карту

Возвращает одну сохраненную карту, включая ее полный объект карты.

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

### Ответ

Возвращает `{ "pass": { ... } }`, одну [запись карты](#pass-record-object).

## Получить список карт

Возвращает постраничный, отсортированный список карт, сохраненных для приложения.

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

### Параметры запроса

| Параметр | Тип | Обязательный | Описание |
| :---- | :---- | :---- | :---- |
| `applicationCode` | string | Да | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code). |
| `orderBy` | string | Нет | Поле для сортировки: `UPDATED` (по умолчанию) или `CREATED`. |
| `orderDirection` | string | Нет | Направление сортировки: `DESC` (по умолчанию, новые сначала) или `ASC`. |
| `page` | integer | Нет | Индекс страницы, начиная с нуля. По умолчанию `0`. |
| `perPage` | integer | Нет | Размер страницы. `0` или пропущенное значение использует значение по умолчанию сервера. |

### Ответ

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `passes` | array of objects | Текущая страница [записей карт](#pass-record-object). |
| `page` | integer | Возвращенный индекс страницы. |
| `perPage` | integer | Размер страницы, использованный для этого ответа. |
| `total` | integer | Общее количество карт для приложения на всех страницах. |

## Установить состояние карты

Активирует или делает недействительной карту. Недействительная (неактивная) карта перемещается в раздел **Просроченные карты** пользователя в Google Wallet; запись сохраняется, чтобы ее можно было повторно активировать.

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

### Тело запроса

| Параметр | Тип | Обязательный | Описание |
| :---- | :---- | :---- | :---- |
| `active` | boolean | Да | `true` устанавливает состояние карты `ACTIVE`; `false` делает ее недействительной (`INACTIVE`). |

### Ответ

Возвращает пустой объект `{}` в случае успеха.

## Удалить карту

Делает карту недействительной в Google и удаляет ее сохраненную запись в Pushwoosh.

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

<Aside type="caution" title="Сохраненную карту нельзя принудительно удалить">
Google не позволяет удалять карту, уже сохраненную на устройстве пользователя. Удаление делает карту недействительной (она перемещается в **Просроченные карты**) и удаляет запись в Pushwoosh.
</Aside>

### Ответ

Возвращает пустой объект `{}` в случае успеха.

## Получить конфигурацию

Возвращает состояние конфигурации Google Wallet для приложения.

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

### Ответ

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `hasServiceAccount` | boolean | Настроен ли ключ сервисного аккаунта. |
| `issuerId` | string | Настроенный [Issuer ID из Google Pay & Wallet Console](/ru/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/#create-the-issuer-account). |
| `serviceAccountEmail` | string | `client_email` настроенного [сервисного аккаунта](/ru/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/#create-the-service-account-key). |

## Шаблоны

Получить список доступных примеров шаблонов карт или загрузить один из них как [объект карты](#pass-object), который можно использовать в качестве отправной точки.

`GET` `/api/google/templates` — возвращает `{ "templates": [ { "filename", "name", "description", "style" } ] }`.

`GET` `/api/google/templates/{filename}` — возвращает `{ "template": { ...объект карты... } }`.

## Справочник объектов

### Объект карты (Pass object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `serialNumber` | string | Присваивается сервером при создании; идентифицирует карту. |
| `generic` / `offer` / `loyalty` / `eventTicket` / `giftCard` / `flight` / `transit` | object | Стиль карты. Должен быть установлен **ровно один**. См. объекты стилей ниже. |
| `hexBackgroundColor` | string | Цвет фона карты, `#rrggbb`. |
| `logoUrl` | string | Публичный HTTPS URL изображения логотипа. Обязательно для карт лояльности и проездных. |
| `heroImageUrl` | string | Публичный HTTPS URL широкого баннерного изображения. |
| `barcode` | object | [Штрих-код](#barcode-object), отображаемый на карте. |
| `textModules` | array | [Текстовые модули](#text-module-object), отображаемые в детальном представлении. |
| `links` | array | [Модули ссылок](#link-module-object), отображаемые в детальном представлении. |
| `expirationTime` | string | Время в формате ISO 8601, когда Google автоматически делает карту просроченной. Пустое значение означает отсутствие срока действия. |
| `appLink` | object | [Ссылка на приложение](#app-link-object): кнопка призыва к действию на лицевой стороне карты. |
| `locations` | array | [Местоположения](#location-object), которые вызывают гео-уведомление (максимум 10). |
| `holdersPolicy` | string | Кто может сохранить карту: `ONE_USER_ALL_DEVICES` (по умолчанию), `ONE_USER_ONE_DEVICE` или `MULTIPLE_HOLDERS`. |

### Универсальный объект (Generic object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `cardTitle` | string | Обязательно. Название эмитента/программы в верхней части карты. |
| `header` | string | Обязательно. Основной заголовок карты. |
| `subheader` | string | Второстепенный заголовок. |
| `cardFields` | array | До 6 [текстовых модулей](#text-module-object), закрепленных на лицевой стороне (до 3 рядов по 2). |

### Объект предложения (Offer object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `title` | string | Обязательно. Например, `Скидка 20% на все`. |
| `provider` | string | Обязательно. Название продавца. |
| `details` | string | Детали предложения. |
| `finePrint` | string | Условия и положения. |
| `redemptionChannel` | string | `ONLINE`, `INSTORE`, `BOTH` (по умолчанию) или `TEMPORARY_PRICE_REDUCTION`. |
| `issuerName` | string | Отображается на поверхностях Google "выпущено"; по умолчанию используется `provider`. |

### Объект лояльности (Loyalty object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `programName` | string | Обязательно. Требует `logoUrl` на карте. |
| `accountName` | string | Имя участника, отображаемое на карте. |
| `accountId` | string | ID участника, отображаемый на карте. |
| `pointsLabel` | string | Например, `Баллы`. Отображается только с балансом. |
| `pointsBalance` | string | Баланс баллов. |
| `rewardsTier` | string | Например, `Золотой`. |
| `rewardsTierLabel` | string | Метка рядом с уровнем; по умолчанию `Уровень`. |
| `issuerName` | string | По умолчанию используется `programName`. |

### Объект билета на мероприятие (Event ticket object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `eventName` | string | Обязательно. |
| `venueName` / `venueAddress` | string | Детали места проведения. |
| `startDateTime` / `endDateTime` | string | ISO 8601 со смещением (например, `2026-07-01T19:30:00+02:00`). |
| `ticketHolderName` / `ticketNumber` / `ticketType` | string | Детали о владельце и билете. |
| `section` / `row` / `seat` / `gate` | string | Детали о месте. |
| `issuerName` | string | По умолчанию используется `eventName`. |

### Объект подарочной карты (Gift card object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `merchantName` | string | Обязательно. |
| `cardNumber` | string | Обязательно. |
| `pin` | string | PIN-код карты. |
| `balance` | string | Десятичная сумма, например `25.00`. Требует `balanceCurrency`. |
| `balanceCurrency` | string | Код валюты ISO 4217, например `USD`. |
| `issuerName` | string | По умолчанию используется `merchantName`. |

### Объект авиабилета (Flight object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `carrierIataCode` | string | Обязательно. 2-буквенный код IATA, например `LX`. |
| `airlineName` | string | Отображаемое название авиакомпании. |
| `flightNumber` | string | Обязательно. Только цифры, например `113`. |
| `originAirportCode` / `destinationAirportCode` | string | Обязательно. 3-буквенные коды IATA. |
| `originTerminal` / `originGate` / `destinationTerminal` | string | Детали терминала и выхода на посадку. |
| `departureDateTime` | string | Обязательно. **Местное** время аэропорта отправления, ISO 8601 **без** смещения (например, `2026-09-01T06:30:00`). |
| `boardingTime` / `arrivalDateTime` | string | Тот же локальный формат. `arrivalDateTime` — местное время в пункте назначения. |
| `passengerName` | string | Обязательно. |
| `confirmationCode` / `seatNumber` / `seatClass` / `boardingGroup` | string | Детали о пассажире. |
| `issuerName` | string | По умолчанию используется `airlineName`, затем код перевозчика. |

### Объект проездного билета (Transit object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `transitType` | string | Обязательно. `BUS`, `RAIL`, `TRAM`, `FERRY` или `OTHER`. |
| `transitOperatorName` | string | Обязательно. Требует `logoUrl` на карте. |
| `passengerName` | string | Обязательно. |
| `ticketNumber` | string | Номер билета. |
| `tripType` | string | `ONE_WAY` (по умолчанию) или `ROUND_TRIP`. |
| `legs` | array | Один или несколько [отрезков пути](#transit-leg-object) в порядке следования. |
| `issuerName` | string | По умолчанию используется `transitOperatorName`. |

### Объект отрезка пути (Transit leg object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `originName` / `destinationName` | string | Обязательно. |
| `departureDateTime` / `arrivalDateTime` | string | ISO 8601; смещение опционально (местное время, если опущено). |
| `platform` / `coach` / `seat` | string | Детали посадки. |
| `fareName` | string | Например, `Anytime Single`. |

### Объект штрих-кода (Barcode object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `format` | string | `QR_CODE`, `PDF_417`, `AZTEC`, `CODE_128`, `EAN_13` и другие типы штрих-кодов Google Wallet. |
| `value` | string | Данные, закодированные в штрих-коде. |
| `altText` | string | Текст, отображаемый под штрих-кодом. |

### Объект текстового модуля (Text module object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `id` | string | Идентификатор модуля. |
| `header` | string | Заголовок модуля. |
| `body` | string | Текст модуля. |

### Объект модуля ссылок (Link module object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `uri` | string | URL внешней ссылки. |
| `description` | string | Метка ссылки, отображаемая в детальном представлении. |

### Объект ссылки на приложение (App link object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `uri` | string | Веб-URL или URI для диплинка. |
| `androidPackageName` | string | Опционально. Если установлено, открывает приложение Android. |
| `description` | string | Внутреннее описание целевого URI (не видимая метка кнопки); по умолчанию используется URI. |

### Объект местоположения (Location object)

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `latitude` | number | от `-90.0` до `+90.0`. |
| `longitude` | number | от `-180.0` до `+180.0`. |

### Объект записи карты (Pass record object)

Возвращается эндпоинтами list/get.

| Поле | Тип | Описание |
| :---- | :---- | :---- |
| `serialNumber` | string | Серийный номер карты. |
| `objectId` | string | Полный идентификатор объекта Google Wallet `{issuerId}.{serialNumber}`. |
| `cardTitle` | string | Отображаемый заголовок/название для карты. |
| `header` | string | Второстепенный отображаемый заголовок. |
| `userId` | string | [User ID Pushwoosh](/ru/developer/api-reference/api-identifiers/#user-id), которому была выдана карта. |
| `createdAt` / `updatedAt` | string | Временные метки создания и последнего обновления. |
| `state` | string | `ACTIVE` или `INACTIVE`. |
| `style` | string | `generic`, `offer`, `loyalty`, `eventTicket`, `giftCard`, `flight` или `transit`. |
| `pass` | object | Полный [объект карты](#pass-object) для редактирования. |