B2B API для продажи Roblox Gift Card
Roblox Gift Card — товар с высоким оборотом и низкой терпимостью к ошибкам: покупатель ждёт код за секунды, а любая путаница с регионом превращается в спор. Автоматизировать продажу можно только через API поставщика, и ниже разобран весь путь интеграции — от чтения каталога до вечерней сверки. Акцент сделан на местах, где обычно теряются деньги, а не на копировании примеров запросов.
Что вообще покупается через API
Через B2B API вы покупаете не «карту Roblox», а конкретную позицию каталога. Позиция определяется тремя параметрами одновременно:
- бренд — Roblox Gift Card;
- номинал — сумма в валюте выпуска;
- регион выпуска — страна или валютная зона, к которой карта привязана.
Ошибка новичков — считать номинал атрибутом одного товара. На практике каждая комбинация номинала и региона ведёт себя как отдельный товар: у неё своя закупочная цена, своё наличие и свои правила активации. Если вы схлопнете их в один листинг с выпадающим списком, рано или поздно вы отдадите покупателю карту не того региона. Подробнее про механику региональных ограничений — в разборе региональных блокировок ключей.
Шаг 1. Разбор каталога и номиналов
Первое, что делает интеграция, — читает каталог. Обычно это два запроса: список категорий и список товаров внутри категории. У FoxReload это GET /api/categories/ и GET /api/products/?category_id_or_slug=...; у каждого товара есть id, name и price, и именно id затем используется как itemId при заказе.
Важные решения на этом шаге:
Кешируйте каталог, но не наличие. Названия, идентификаторы и структура номиналов меняются редко — их можно синхронизировать раз в несколько часов. Наличие меняется постоянно, и продавать из кеша нельзя: проверка должна выполняться в момент оформления заказа.
Не парсите номинал из названия регулярным выражением. Название — человекочитаемая строка, она может измениться. Сопоставляйте свои листинги с товарами поставщика по идентификатору и храните эту связку в своей базе.
Заведите явную карту соответствия. Одна строка на каждый ваш листинг: ваш SKU, идентификатор товара у поставщика, номинал, регион, дата последней сверки. Эта таблица потом спасает при сверке и при смене поставщика.
Шаг 2. Проверка баланса и предусловия заказа
Оптовая покупка через API идёт с баланса, заранее внесённого поставщику. Это значит, что у вас есть предусловие, которое не зависит от покупателя: если баланса нет, заказ не пройдёт.
Практическая схема:
| Порог | Что происходит | Кто реагирует |
|---|---|---|
| Предупредительный | Уведомление в рабочий чат | Финансы пополняют счёт |
| Критический | Дорогие номиналы уходят с витрины | Автоматика |
| Ноль | Приём заказов остановлен | Автоматика |
Отдельно обрабатывайте отказ «недостаточно средств» как самостоятельный код ошибки. Общий обработчик сбоев обычно ретраит запрос — здесь ретрай бессмысленен и только запутывает журнал. Проверить, что ключ вообще работает и виден ваш аккаунт, у FoxReload можно вызовом GET /api/access/me.
Шаг 3. Создание заказа
Заказ создаётся вызовом POST /api/orders с массивом позиций: идентификатор товара и количество. Три правила, которые стоит зафиксировать до написания кода:
- Пишите заказ в свою базу до отправки запроса, а не после. Если ответ потеряется, у вас должна остаться запись о попытке.
- Не используйте таймаут как доказательство неудачи. Таймаут означает «я не знаю результат», а не «заказа нет». Перед повторной попыткой всегда перечитывайте состояние на стороне поставщика.
- Тестируйте на мок-режиме. У FoxReload за это отвечает флаг
isMock: trueв теле запроса — он вернёт тестовые коды, не списывая баланс.
Отдельно про идемпотентность: заголовок Idempotency-Key у FoxReload не поддерживается, поэтому защита от дублей строится на вашей стороне — уникальный ключ операции в вашей базе плюс обязательное перечитывание перед ретраем. Если ваш поставщик заявляет поддержку идемпотентных ключей, проверьте это в его документации, прежде чем на неё закладываться.
Шаг 4. Получение кода — только опросом
Здесь находится главное недопонимание в интеграциях подарочных карт. Статус заказа вы узнаёте опросом, если только конкретный поставщик не документировал колбэки.
У FoxReload вебхуков нет: вы вызываете GET /api/orders/{order_id} до финального статуса, и при completed коды лежат в items[].externalData. Вебхуки и HMAC-подписанные колбэки — это то, что может предлагать какой-то поставщик; никогда не предполагайте их наличие по умолчанию и всегда сверяйтесь с документацией конкретного API.
Правильный опрос выглядит так:
- нарастающий интервал — часто в первые секунды, реже дальше;
- общий лимит времени, после которого заказ уходит в очередь ручной проверки, а не висит вечно;
- финальные и нефинальные статусы разделены явно — код не должен трактовать неизвестный статус как успех;
- частичное выполнение обрабатывается по позициям: в многопозиционном заказе одна позиция может выполниться, а другая — нет.
Детальный разбор этого этапа — в статье про получение кода через API подарочных карт, а общая последовательность подключения описана в руководстве по подключению API поставщика.
Шаг 5. Хранение кода и доставка покупателю
Как только код получен, он становится вашей ответственностью. Минимальный контур безопасности:
- шифрование при хранении на уровне приложения — ключ живёт в секрет-менеджере, а не в коде и не в переменной рядом с базой;
- доступ к расшифровке только у сервиса выдачи;
- код не пишется в логи, трассировки, аналитику и тикеты поддержки;
- хэш кода хранится рядом — он даёт доказательство в споре без второй открытой копии.
Доставка покупателю — отдельная операция со своим статусом. Показали код на странице подтверждения — зафиксировали факт показа с меткой времени. Продублировали письмом — зафиксировали отправку. В споре «мне ничего не пришло» вас защищает именно этот журнал, а не память менеджера.
Шаг 6. Сверка
Раз в сутки сводите три набора данных: ваши продажи, ваши заказы у поставщика и списания с баланса. Расхождение любого знака — сигнал.
- Продажа есть, заказа нет → покупателю не выдан код.
- Заказ есть, продажи нет → вы купили код, который никому не продали.
- Списание есть, заказа нет → разбираться с поставщиком.
Сверка занимает минуты, если у вас есть карта соответствия SKU и отдельные записи по этапам. Без них она превращается в ручное расследование по скриншотам.
Где брать сам товар
Roblox Gift Card имеет смысл закупать там, где вместе с номиналами доступны и другие ходовые позиции — иначе вы будете держать по интеграции на каждый бренд. FoxReload закрывает это одним контуром: оптовый каталог на 900+ SKU, единый REST API, автоматическая выдача и мультирегиональные позиции, так что один и тот же код интеграции обслуживает и подарочные карты, и игровые пополнения, и ключи. Сравнить условия можно по ценам ниже, а перед первым депозитом стоит пройти проверку поставщика.