Генерация и добавление купонов в Apple Wallet: от pkpass до погашения

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.yourshop.coupon",
  "serialNumber": "COUPON-SUMMER-USER789",
  "teamIdentifier": "ABCDE12345",
  "organizationName": "YourShop",
  "description": "Скидка 20% на летнюю коллекцию",
  "foregroundColor": "rgb(255,255,255)",
  "backgroundColor": "rgb(200,50,50)",
  "coupon": {
    "primaryFields": [
      {
        "key": "offer",
        "value": "−20%",
        "label": "Скидка на всё"
      }
    ],
    "secondaryFields": [
      {
        "key": "expires",
        "value": "через 1 месяц от генерации",
        "label": "Действует до",
        "dateStyle": "PKDateStyleShort",
        "timeStyle": "PKDateStyleNone"
      }
    ],
    "auxiliaryFields": [
      {
        "key": "conditions",
        "value": "При покупке от определённой суммы",
        "label": "Условия"
      }
    ],
    "barcode": {
      "message": "COUPON-SUMMER-USER789",
      "format": "PKBarcodeFormatCode128",
      "messageEncoding": "iso-8859-1"
    }
  },
  "expirationDate": "через 30 дней",
  "voided": false
}

Поле voided: true визуально зачёркивает карточку и перемещает её в архив. Устанавливается через push-обновление после погашения. Для отправки обновлений используем APNs с сертификатом Push Notification (тип Pass Type). У каждого пасса свой pushToken, который регистрируется при первом добавлении.

Как гарантировать, что купон не будет использован дважды?

Логика погашения полностью на сервере. QR-код содержит serialNumber или уникальный токен. Касса сканирует код, сервер проверяет, не истёк ли купон и не погашен ли он. После успешного применения устанавливает флаг used = true и отправляет push APNs → устройство скачивает обновлённый .pkpass с voided: true. Если push не дошёл, при следующем сканировании касса отклоняет дубликат. Такой механизм исключает двойное использование даже при ошибках сети.

Как организовать массовую рассылку?

Запрос POST /campaigns/{id}/distribute ставит задачу в очередь. Воркеры генерируют пассы партиями по 500 штук, записывают ссылки в БД. Пользователи получают push с кнопкой «Добавить в Wallet» по мере генерации. Каждый купон — уникальный serialNumber и authenticationToken. Нельзя раздавать одинаковые пассы разным пользователям — системы обновлений начнут конфликтовать. Среднее время генерации 10 000 купонов — 15–20 секунд при 10 воркерах.

Почему асинхронная генерация быстрее синхронной?

Асинхронная генерация в 2.5 раза быстрее синхронной при массовой рассылке. Это позволяет обрабатывать пиковые нагрузки без потери производительности и даёт прирост конверсии.

Типичные ошибки при интеграции

• Не установлен voided: true после погашения — купон остаётся активным, можно использовать повторно. Всегда отправляйте push-обновление.
• Дублирование serialNumber — если два пользователя получат одинаковый идентификатор, обновления для одного перезапишут другой. Генерируйте уникальный ID для каждого.
• Неправильный MIME-type — сервер должен отдавать application/vnd.apple.pkpass, иначе iOS Safari не предложит добавить в Wallet.
• Превышение лимита локаций — больше 10 точек продаж в одном пассе игнорируются. Разделите на несколько купонов.

Пошаговая инструкция по добавлению купона в Wallet

1. Получите сертификат Wallet в Apple Developer Console.
2. Сгенерируйте .pkpass с уникальным serialNumber и подпишите его.
3. Разместите файл на сервере и отправьте пользователю ссылку.
4. При погашении отправьте push-обновление с voided: true.

Сроки и объём работ

Интеграция купонов в Apple Wallet занимает от 1 до 3 дней в зависимости от сложности массовой рассылки и геотаргетинга. Стоимость рассчитывается индивидуально. Наша команда имеет многолетний опыт в разработке iOS-приложений и реализовала более 10 интеграций Apple Wallet. Получите консультацию — мы подготовим коммерческое предложение в течение дня.

Отметим: Что входит:

• Проектирование структуры пасса под ваши купоны.
• Генератор .pkpass с подписью и push-обновлениями.
• API для погашения с проверкой на стороне сервера.
• Тестовые купоны и инструкция по добавлению в Wallet.
• Поддержка после запуска в течение месяца.

Таблица сравнения типов пассов (для справки)

Для купонов используем тип coupon — он даёт визуальный стиль, который пользователи сразу распознают как скидку. Свяжитесь с нами, чтобы обсудить ваши сценарии. Оцените свой проект — мы подберём оптимальный сценарий интеграции, настроим генерацию и гарантируем корректную работу push-обновлений.