Вебхуки для заказов цифровых товаров

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

FoxReload не предоставляет вебхуки. Статус заказа и коды доставки получаются опросом GET /api/orders/{order_id}. Когда status == "completed", поле items[].externalData содержит массив кодов. При ошибке позиции — items[].error. Это руководство объясняет, как правильно построить опрос статусов, асинхронную обработку и при желании — собственный слой push-уведомлений для ваших клиентов поверх результата опроса.

Определение: Опрос статуса заказа — периодические запросы GET /api/orders/{order_id} к API FoxReload для проверки готовности кодов. При status == "completed" код доставляется клиенту. Вебхуков от FoxReload нет; если вы хотите push-уведомлять своих клиентов — стройте этот слой самостоятельно на основе результата опроса.

Главный вывод: FoxReload не имеет вебхуков. Надёжный опрос GET /api/orders/{id} с экспоненциальным откатом при 429/ошибках сетей — единственный способ получить статус и коды. Для уведомления ваших клиентов стройте собственный слой: фоновый воркер опрашивает FoxReload → при завершении отправляет email/Telegram/push вашему покупателю.

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

• Разработчики, интегрирующие FoxReload API и строящие асинхронную обработку заказов
• Операторы магазинов, у которых фулфилмент заказов иногда занимает время (processing → completed)
• Все, кто хочет рассылать push-уведомления своим клиентам о готовности кодов

Как работает получение статуса в FoxReload

FoxReload не отправляет push-уведомления. Единственный способ узнать статус — опрос:

При малых объёмах опрос каждые 3–5 секунд полностью достаточен. При высоких объёмах используйте очередь задач: создали заказ → положили задачу опроса в очередь → воркер опрашивает до завершения.

Статусы заказов FoxReload

В ответе GET /api/orders/{order_id} возможны следующие статусы:

При status == "completed" поле items[].externalData содержит массив кодов доставки.

Формат ответа при завершении

{
  "id": "order_01k...",
  "status": "completed",
  "items": [
    {
      "itemId": "product_01k...",
      "externalData": ["XXXXX-YYYYY-ZZZZZ"],
      "error": null
    }
  ]
}

Проверяйте status и items[].externalData — это единственный способ получить коды от FoxReload. При ошибке позиции items[].error содержит описание.

Реализация опроса статусов

Правильная архитектура для опроса FoxReload:

После POST /api/orders/ → получен order_id
  → Поместить задачу опроса в очередь (BullMQ, Celery, cron)

Фоновый воркер
  → GET /api/orders/{order_id}
  → Если status == 'completed': извлечь externalData → доставить код клиенту
  → Если status == 'failed'/'cancelled': обработать ошибку, уведомить ops
  → Иначе: повторить через 3–5 секунд (экспоненциальный откат при 429)

Правильно: обработка в фоновом воркере, не в синхронном запросе клиента.

Предотвращение дублирования заказов

FoxReload не имеет idempotency-ключей. Перед повторным созданием заказа всегда проверяйте статус предыдущего через GET /api/orders/{id}, чтобы не задвоить заказ при сетевых сбоях:

# Перед повторным POST /api/orders/ проверьте существующий
existing = get_order_from_db(internal_ref)
if existing:
    status = foxreload_get(f'/api/orders/{existing.foxreload_id}')
    if status['status'] in ('active', 'paid', 'processing', 'completed'):
        return  # Заказ уже существует — не создавать повторно

Построение собственного слоя уведомлений

Если вы хотите отправлять push-уведомления своим клиентам (email, Telegram, SMS), постройте этот слой самостоятельно поверх результата опроса FoxReload:

Воркер опрашивает GET /api/orders/{id} до completed
  → Получает externalData (коды)
  → Отправляет уведомление своему клиенту (email/bot.sendMessage/push)
  → Обновляет статус в своей БД

Это ваша собственная инфраструктура уведомлений — FoxReload в ней не участвует.

Опрос для незавершённых заказов (резервный сценарий)

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

Планировщик (каждые 5 минут):
  → Найти все заказы со статусом != completed/failed/cancelled и возрастом > 5 минут
  → Для каждого: вызвать GET /api/orders/{id}
  → Если статус = completed: обработать доставку
  → Если статус = failed/cancelled: уведомить операторов

Чек-лист реализации

• Авторизация через заголовок X-API-Key настроена
• После POST /api/orders/ сохраняется order_id в БД
• Фоновый воркер опрашивает GET /api/orders/{id} до завершения
• Обрабатываются все статусы: completed, failed, cancelled
• При completed — items[].externalData доставляется клиенту
• При failed — items[].error логируется; операторы уведомляются
• Экспоненциальный откат при сетевых ошибках и 429
• Проверка существующего заказа перед повторным созданием (защита от дублей)
• Планировщик для застрявших заказов (>5 мин в processing) настроен
• Мониторинг баланса — при ошибке BalanceNotEnough пополнить через /api/topups/crypto/