Как автоматизировать доставку цифровых кодов

Краткий ответ

Автоматизация доставки цифровых кодов означает замену ручной обработки заказов конвейером: оплата покупателем запускает API-вызов к поставщику, поставщик возвращает код, а система доставляет его покупателю — всё в течение секунд. Шесть компонентов: слушатель события оплаты, вызов API создания заказа, разбор кода из ответа, доставка покупателю (email/страница/сообщение), слушатель вебхука для асинхронных обновлений и обработка ошибок для неудачных заказов. Рабочая автоматизация обрабатывает неограниченное количество заказов без ручных шагов.

Определение: Автоматизированная доставка цифрового кода — конвейер фулфилмента, соединяющий оплату покупателем с доставкой кода без вмешательства человека — с использованием создания заказов через API, вебхук-событий и программной раздачи кодов.

Главный вывод: Ручная доставка кодов не масштабируется: она создаёт задержки, человеческие ошибки и нагрузку на поддержку. Автоматизация устраняет все три проблемы. Один разработчик может построить систему, обрабатывающую тысячи ежедневных заказов с теми же усилиями, что и десяток.

Для кого это руководство

• Разработчики, создающие магазины цифровых товаров и реализующие конвейер доставки
• Владельцы магазинов, доставляющие коды вручную и желающие автоматизироваться
• Разработчики Telegram-ботов, желающие автоматизировать доставку пополнений и подарочных карт

Почему ручная доставка не масштабируется

При 20 заказах в день ручная работа справляется. При 200 — становится узким местом. При 2 000 — ломается.

Конвейер автоматизированной доставки

[Покупатель платит]
      │
      ▼
[Вебхук/коллбэк платёжного шлюза срабатывает]
      │
      ▼
[Обработчик заказа: валидация платежа, построение запроса заказа]
      │
      ▼
[POST /orders в API поставщика]
      │
      ├─[Успех]──▶ [Разбор кода из ответа]
      │                      │
      │                      ▼
      │              [Доставка кода покупателю]
      │              (email / страница заказа / сообщение бота)
      │
      └─[Ошибка]──▶ [Логировать, оповестить ops, вернуть деньги при необходимости]

Компонент 1: Слушатель события оплаты

Конвейер фулфилмента начинается, когда оплата подтверждена — не когда она инициирована.

Правила:

• Запускать фулфилмент только на подтверждённое событие оплаты (не на создание заказа)
• Обрабатывать идемпотентность: если одно и то же событие оплаты срабатывает дважды, не создавать два заказа
• Валидировать, что сумма оплаты совпадает с ожидаемой стоимостью продукта

Большинство платёжных шлюзов (Stripe, PayPal и др.) отправляют вебхук-событие при подтверждении оплаты. Подпишитесь на правильный тип события:

• Stripe: payment_intent.succeeded
• PayPal: PAYMENT.CAPTURE.COMPLETED

Никогда не запускайте вызов API поставщика со стороны клиента (браузера). Всегда со своего сервера.

Компонент 2: Вызов API создания заказа

После подтверждения оплаты вызовите эндпоинт создания заказа поставщика:

POST /orders
Content-Type: application/json
Authorization: Bearer {api_key}

{
  "sku": "steam-20-usd",
  "quantity": 1,
  "reference": "ORD-{your_order_id}"
}

Используйте ваш внутренний ID заказа как reference. Это позволяет сверять заказы поставщика с вашей базой данных. Делайте его уникальным для каждого заказа.

Действия по ответам:

Компонент 3: Разбор кода

Ответ API обычно содержит код в структурированном формате. Разберите и валидируйте перед доставкой:

{
  "order_id": "SUP-99887",
  "status": "completed",
  "items": [
    {
      "code": "XXXXX-YYYYY-ZZZZZ",
      "pin": null,
      "instructions": "Redeem at store.steampowered.com"
    }
  ]
}

Валидируйте:

• status равен completed (не pending или failed)
• Поле code не null и не пустое
• Если продукт требует PIN, поле pin не null

Для продуктов пополнения ответ может содержать подтверждение доставки вместо кода.

Компонент 4: Доставка покупателю

Доставьте код через канал, который используют ваши покупатели:

Всегда включайте с кодом:

• Сам код (в удобном для копирования формате)
• Название продукта и номинал
• Инструкции по активации или ссылку
• Контакт вашей поддержки

Компонент 5: Слушатель вебхуков для асинхронных заказов

Для заказов, не выполненных мгновенно (статус pending), используйте вебхуки для получения обновления при завершении фулфилмента:

Требования к обработчику вебхуков:

1. Принять POST-запрос от IP/домена поставщика
2. Верифицировать подпись вебхука (HMAC или аналог)
3. Вернуть HTTP 200 в течение 5 секунд
4. Поставить событие в очередь для асинхронной обработки
5. Обработать: если status = completed → доставить код покупателю

Не делайте:

• Бизнес-логику внутри синхронного обработчика вебхука
• Возвращать не-200, если не хотите, чтобы поставщик повторил попытку
• Предполагать, что порядок вебхуков соответствует порядку создания заказов

Компонент 6: Обработка ошибок

Пути ошибок требуют столько же проектирования, сколько и «счастливый путь».

Мониторинг и оповещения

Настройте мониторинг по:

Чек-лист интеграции

• Обработчик вебхука подтверждения оплаты реализован и протестирован
• Логика идемпотентности: дублированные события не создают дублированные заказы
• Вызов API создания заказа поставщика реализован с заголовком авторизации
• Все статусы ответов обработаны: completed, pending, failed
• Разбор кода валидирует непустоту поля code
• Доставка покупателю реализована для вашего основного канала
• Доставка включает код + название продукта + инструкции по активации + контакт поддержки
• Слушатель вебхуков с валидацией подписи
• Вебхук-события обрабатываются асинхронно
• Резервный опрос для pending-заказов (если вебхуки недоступны)
• Логирование ошибок с оповещениями
• Мониторинг баланса с оповещением о низком балансе
• Нагрузочное тестирование при ожидаемом пиковом объёме