FoxReload API: быстрый старт 2026 — первый запрос за 10 минут

Этот быстрый старт FoxReload API написан для бэкенд-разработчиков и инженеров закупок, которым нужно интегрировать оптовый каталог цифровых товаров в свой витринный сайт, ERP или внутренние инструменты. К концу статьи вы сделаете реальный авторизованный запрос к https://public-api.foxreload.com/api/categories/ и разберёте JSON-ответ.

1. Получите API-ключ

Откройте личный кабинет FoxReload, перейдите в раздел API и создайте ключ. Ключ показывается один раз — немедленно сохраните его в безопасное место (секрет-менеджер, env variable). При необходимости ограничьте ключ по IP или CIDR (до 10 записей).

Никогда не коммитьте ключи в git. Храните их в секрет-менеджере (AWS Secrets Manager, Doppler, Vault) и инжектите в рантайме.

2. Заголовок авторизации

FoxReload использует авторизацию через заголовок X-API-Key. Никаких Bearer-токенов, OAuth, client_id/client_secret не существует. Каждый запрос должен содержать:

X-API-Key: YOUR_API_KEY
Content-Type: application/json

Запросы без ключа возвращают HTTP 401. Ключ с IP вне allowlist возвращает HTTP 403. Принимается только HTTPS.

3. Проверка ключа

Самый простой способ убедиться, что ключ работает, — вызвать GET /api/access/me:

curl "https://public-api.foxreload.com/api/access/me" \
  -H "X-API-Key: YOUR_API_KEY"

Успешный вызов возвращает HTTP 200:

{
  "email": "partner@example.com",
  "telegramId": null,
  "firstName": "Иван",
  "lastName": "Иванов",
  "isActive": true,
  "isSuper": false
}

4. Первый curl — просмотр каталога

Просмотрите категории товаров:

curl "https://public-api.foxreload.com/api/categories/?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Затем получите товары конкретной категории (параметр category_id_or_slug обязателен):

curl "https://public-api.foxreload.com/api/products/?category_id_or_slug=gift-cards&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Ответ:

[
  {
    "id": "product_01krgfgww8eth9xvvysd6y7r4j",
    "name": "PlayStation Network Turkey 100 TRY",
    "price": "2600.00"
  }
]

Поле id товара — это itemId для создания заказа.

5. Поиск товаров

curl "https://public-api.foxreload.com/api/products/search?query=PlayStation&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Параметр query обязателен. Дополнительно: category_id_or_slug, limit.

6. Создание тестового заказа

Для тестирования используйте isMock: true — заказ вернёт мок-коды без реального списания (sandbox-окружения не существует, это штатный способ тестировать):

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
      }
    ],
    "isMock": true
  }'

Ответ HTTP 201 с объектом заказа:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "price": "2600.00",
  "isMock": true,
  "status": "active",
  "cancelReason": null,
  "createdAt": "2026-05-18T10:00:00Z",
  "paymentExpiresAt": "2026-05-18T10:30:00Z",
  "items": [...]
}

7. Получение кодов опросом

FoxReload не поддерживает webhooks. Результат заказа получается опросом GET /api/orders/{order_id}:

curl "https://public-api.foxreload.com/api/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: YOUR_API_KEY"

Когда status == "completed" — коды находятся в items[].externalData.

8. Лимиты и ошибки

При превышении rate limit возвращается HTTP 429. Реализуйте экспоненциальный backoff и никогда не ретраите на HTTP 4xx, кроме 429. Серверные ошибки (5xx) безопасно ретраить.

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

Готовы внедрить это в свой стек? Зарегистрируйтесь на foxreload.com и начните закупать цифровые товары по оптовой марже уже на этой неделе.