> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yume.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Брендированная выдача пропусков

> Публичные адреса выдачи карт Wallet: файл карты для Apple Wallet и ссылка сохранения для Google Wallet по бонусной карте клиента или заказу аренды текущей компании.

Полный перечень полей — в [глоссарии](/ru/logic/wallet/issue-glossary).

## Что делает раздел

Раздел отвечает за публичную выдачу брендированных карт Wallet: по прямой ссылке клиент (или сотрудник компании) получает карту либо файлом для Apple Wallet, либо ссылкой для сохранения в Google Wallet. Карты бывают двух видов: бонусная карта клиента и карта конкретного заказа аренды.

Есть четыре публичных адреса выдачи:

| Что выдаётся           | Формат        | Что возвращается           |
| ---------------------- | ------------- | -------------------------- |
| Бонусная карта клиента | Apple Wallet  | Файл карты (скачивается)   |
| Заказ аренды           | Apple Wallet  | Файл карты (скачивается)   |
| Бонусная карта клиента | Google Wallet | JSON со ссылкой сохранения |
| Заказ аренды           | Google Wallet | JSON со ссылкой сохранения |

Во всех адресах объект указывается по числовому идентификатору в пути (идентификатор бонусной карты или идентификатор заказа).

<Info>
  Компания определяется не в самом разделе, а раньше — по домену запроса или служебному заголовку компании. Раздел просто работает с «текущей компанией», уже выбранной для запроса, и загружает бонусную карту либо заказ для этой компании.
</Info>

## Как выдаётся карта Apple Wallet

### Общий порядок

1. Определяется текущая компания.
2. По идентификатору из ссылки находится объект — бонусная карта или заказ — в пределах этой компании.
3. Если объект не найден — возвращается ошибка «не найдено».
4. Находится или создаётся Пропуск (карта Wallet) для этой пары «компания + объект».
5. Собирается файл карты и отдаётся на скачивание.

### Поиск или создание Пропуска

Ключевой шаг — гарантировать один Пропуск на объект внутри компании. Система ищет уже существующий Пропуск по совокупности: Компания, Тип пропуска (бонусная карта или заказ), Идентификатор связанного объекта и Идентификатор типа пропуска (берётся из настроек приложения). Если такой Пропуск есть — он переиспользуется; если нет — создаётся новый, и ему присваивается свежий уникальный Серийный номер (случайное шестнадцатеричное значение).

<Note>
  Токен авторизации новому Пропуску не задаётся в этом разделе — он проставляется автоматически самим Пропуском при создании (случайное шестнадцатеричное значение). Этот токен потом используется веб-сервисом Apple для проверки запросов от устройства.
</Note>

### Формирование файла и заголовки скачивания

После получения Пропуска собирается сам файл карты, и ответ оформляется так, чтобы браузер/устройство восприняли его как загружаемую карту Wallet:

* тип содержимого — карта Apple Wallet;
* заголовок вложения с именем файла;
* заголовок «Последнее изменение», равный времени поля Обновлён у Пропуска.

Имена файлов различаются по виду карты:

| Вид карты      | Имя файла                                           |
| -------------- | --------------------------------------------------- |
| Бонусная карта | файл карты с идентификатором бонусной карты в имени |
| Заказ          | файл карты с номером заказа в имени                 |

## Как выдаётся ссылка Google Wallet

Для Google Wallet файл не собирается и Пропуск в системе не создаётся. Раздел возвращает JSON с единственным полем — ссылкой сохранения. Переход по этой ссылке добавляет карту в Google Wallet на стороне Google.

<Info>
  Важное отличие от Apple: при выдаче через Google запись Пропуска (карты Wallet) в базе не заводится. Соответственно фоновые push-обновления через Apple к таким картам не относятся — они касаются только выпущенных Apple-пропусков.
</Info>

## Проверки перед выдачей

Правила «когда отдать карту, а когда ошибку» немного различаются по видам:

| Адрес                         | Требование к объекту                          | Если не выполнено   |
| ----------------------------- | --------------------------------------------- | ------------------- |
| Бонусная карта, Apple Wallet  | Бонусная карта существует                     | Ошибка «не найдено» |
| Заказ, Apple Wallet           | Заказ существует и у него есть клиент         | Ошибка «не найдено» |
| Бонусная карта, Google Wallet | Бонусная карта существует и у неё есть клиент | Ошибка «не найдено» |
| Заказ, Google Wallet          | Заказ существует и у него есть клиент         | Ошибка «не найдено» |

<Warning>
  Для карты заказа наличие привязанного клиента обязательно во всех форматах: без клиента карту выдать нельзя. Для бонусной карты в Apple Wallet явной проверки клиента нет (проверяется только существование самой бонусной карты), тогда как для Google Wallet проверка клиента у бонусной карты есть.
</Warning>

## Как это используется

Эти адреса — точка входа для клиента: обычно ссылку на выдачу карты клиент получает в сообщении или на веб-странице компании, открывает её, и карта попадает в его Apple или Google Wallet. Так как выдача публичная (без входа в систему), доступ к конкретной карте определяется знанием адреса и идентификатора объекта в пределах домена компании.

Выпущенные Apple-пропуски дальше живут своей жизнью: устройство регистрируется в веб-сервисе Apple, а изменения заказа автоматически помечают соответствующий Пропуск обновлённым и запускают фоновую рассылку push-обновлений. Эти механизмы описаны в других разделах модуля.

## Связанные страницы

<CardGroup cols={2}>
  <Card title="Глоссарий: Брендированная выдача пропусков" icon="book" href="/ru/logic/wallet/issue-glossary">
    Полный перечень полей и понятий, задействованных при публичной выдаче карт.
  </Card>

  <Card title="Карты в Apple Wallet и Google Wallet" icon="wallet" href="/ru/logic/wallet">
    Обзор раздела: какие бывают карты, как их получает клиент и как они обновляются.
  </Card>

  <Card title="Проблемы и логические ошибки" icon="bug" href="/ru/logic/wallet/issues">
    Сводка известных проблем и логических ошибок всего модуля кошельков.
  </Card>

  <Card title="Что хранится о карте" icon="id-card" href="/ru/logic/wallet/model">
    Какие сведения система хранит о выпущенной карте и о телефонах, подписанных на обновления.
  </Card>

  <Card title="Оформление карты Apple" icon="apple" href="/ru/logic/wallet/apple-card">
    Что клиент видит на карте: поля, QR-код, фирменные цвета и логотип.
  </Card>

  <Card title="Карта в Google Wallet" icon="google" href="/ru/logic/wallet/google">
    Как формируется карта и ссылка сохранения для Google Wallet.
  </Card>

  <Card title="Как телефон получает свежую карту" icon="mobile-screen" href="/ru/logic/wallet/card-refresh">
    Что происходит между телефоном клиента и системой, когда карта обновляется.
  </Card>

  <Card title="Уведомления об обновлении карты" icon="paper-plane" href="/ru/logic/wallet/card-updates">
    Бесшумные уведомления, которые заставляют телефон перекачать карту.
  </Card>

  <Card title="Что запускает обновление" icon="arrows-rotate" href="/ru/logic/wallet/change-dispatch">
    Какие изменения заказа приводят к обновлению карты у клиента.
  </Card>
</CardGroup>