Order Flow FoxReload: создание заказа, обработка, получение кодов

Если вы интегрируете FoxReload в масштабе, нужно аккуратно смоделировать состояние заказа на своей стороне: поддержка клиентов, сверка и мониторинг — всё зависит от понимания того, что означает каждое состояние и когда происходят переходы. Эта статья проходит по полному order flow FoxReload в том виде, как он реально работает в продакшене.

Шесть состояний заказа

Каждый заказ проходит через следующие статусы. Большинство happy-path заказов завершается за несколько секунд или минут.

State machine строго однонаправленная. Объект заказа содержит поля: id (uuid), price, isMock, status, cancelReason, createdAt, paymentExpiresAt, items[].

1. Создание заказа

Вызовите POST /api/orders с X-API-Key и телом:

curl -X POST "https://public-api.foxreload.com/api/orders" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "itemId": "product_01krgfgww8eth9xvvysd6y7r4j",
        "quantity": 1,
        "note": {"player_id": "123456"}
      }
    ],
    "isMock": false
  }'

itemId — это id товара из GET /api/products/. В ответ вернётся объект заказа со статусом active и HTTP 201.

Параметры тела:

• items (обязательно, 1–10 позиций): каждая позиция содержит itemId, quantity, опциональные totalPrice и note (до 10 ключей для дополнительных данных, например UID игрока).
• isMock (опционально, по умолчанию false): при true заказ вернёт мок-коды — это правильный способ тестировать без реального списания. Sandbox-окружения не существует.

Если баланса не хватает — ошибка BalanceNotEnough. Баланс пополняется криптой через POST /api/topups/crypto/.

2. Active → paid → processing → completed

После создания заказ получает статус active. Средства с баланса списываются автоматически — заказ переходит в paid, затем в processing (fulfilment у поставщика), затем в completed.

Коды получаются опросом, а не через вебхуки (FoxReload не поддерживает вебхуки). Когда status == "completed", каждая позиция items[] содержит:

• product — объект с id, name, userGuide, attributes, isService, categoryId
• externalData[] — массив выданных кодов/PIN
• error — возможная ошибка по данной позиции

curl "https://public-api.foxreload.com/api/orders/{order_id}" \
  -H "X-API-Key: YOUR_API_KEY"

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

3. Оплата внешним способом

Если вы хотите создать внешний платёж под конкретный заказ (через платёжного провайдера, а не с баланса), вызовите:

curl -X POST "https://public-api.foxreload.com/api/orders/{order_id}/pay" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentProvider": "pally",
    "paymentMethodType": "sbp",
    "paymentReturnUrl": "https://yourdomain.com/order-complete"
  }'

Доступные провайдеры: pally (по умолчанию), yookassa, tbank. Типы методов: bank_card, sbp (по умолчанию) и другие. Ответ содержит {id, confirmationToken, confirmationUrl, returnUrl}.

4. Cancelled и failed

Cancelled — заказ отменён. Поле cancelReason уточняет причину:

• payment_failure — оплата не прошла
• payment_expiration — истёк срок оплаты (paymentExpiresAt)
• user_request — отмена по инициативе пользователя

Failed — fulfilment не удался. Смотрите items[].error для диагностики по каждой позиции.

5. Список заказов

curl "https://public-api.foxreload.com/api/orders/?statuses=active,processing&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Параметр statuses принимает значения через запятую: active, paid, processing, completed, cancelled, failed. Дополнительно: limit, offset.

Надёжная обработка в продакшене

Поскольку в FoxReload нет idempotency-ключей и webhooks, соблюдайте два правила:

1. Перед повторным созданием заказа — проверьте GET /api/orders/ на наличие существующего активного заказа по той же позиции, чтобы не создать дубль.
2. При сетевых ошибках или 429 — используйте экспоненциальный backoff; не спамьте запросами создания нового заказа без проверки предыдущего.

Полный гайд по retry-паттернам — в статье Retry/backoff паттерны для B2B-интеграций.