GameCore Supply API — оптовые пополнения игр через один API

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

Эти страницы описывают API таким, какой он есть сегодня: всё сверено с работающим кодом, а не с планами. Доступ выдаётся при подключении — формы самостоятельной регистрации здесь нет, — а быстрее всего начать с Быстрого старта.

С чем вы интегрируетесь

Считайте нас складом, а не платёжным сервисом. На нас — товар и отношения с поставщиками, на вас — витрина и покупатель.

Три свойства определяют всё остальное:

• Один каталог, несколько поставщиков. Игры, категории и номиналы приходят из нескольких источников и приводятся к единой модели с единым набором эндпоинтов. Какой поставщик исполнит конкретный SKU — наша забота, а не ваша, и наружу это не выносится.
• Один ключ, один баланс. Каждый вызов идёт с одним и тем же заголовком X-Api-Key. Заказы оплачиваются с вашего B2B-баланса — по предоплате или в кредит в пределах согласованного лимита, — никогда картой и никогда покупателем.
• Оптовые цены в рублях. Любая цена, которую мы отдаём, — это оптовая цена вашего аккаунта в рублях, то есть цена до вашей скидки за объём. Скидка тарифа применяется в момент создания заказа, к каждой его строке, поэтому списание может оказаться меньше суммы каталожных цен, прочитанных секундой раньше; в ответах каталога она не показывается никогда. Цену при заказе вы не передаёте: в теле заказа только товары и количества, а считаем мы в момент создания заказа. Про тарифы — на странице Цены.

Понятия «покупатель» в этом API нет вообще. Нет учётных записей покупателей, нет их логинов, нет отдельных токенов. Есть вы, ваш баланс и ваши заказы.

Кто за что отвечает

Две границы стоит проговорить прямо — ошибка на любой из них дорого стоит:

Мы проверяем форму данных доставки, но не их истинность. Там, где для семейства игр есть форматное правило, мы применяем его до списания: количество цифр, «только цифры», допустимые варианты select. Чего мы не делаем никогда — не проверяем, что такой аккаунт существует и что он принадлежит заплатившему покупателю. Корректный по форме чужой ID будет пополнен, и отозвать это нельзя. Поэтому ввод и подтверждение ID живут в вашей воронке — см. Прямое пополнение по API.

Наши вебхуки адресованы вашему бэкенду, а не вашему покупателю. Они сообщают вашей системе, что заказ разрешился. Что делать дальше — письмо, страница в личном кабинете, сообщение в Telegram — решаете вы.

Как устроена интеграция

Обычная последовательность целиком:

1. Покупатель смотрит ваш каталог, который вы держите в синхронизации с нашим.
2. Покупатель оформляет заказ и платит вам — вашим способом.
3. Ваш бэкенд записывает собственный заказ и вызывает POST /b2b/orders с заголовком X-Idempotency-Key.
4. Мы списываем с баланса и создаём заказ в одной транзакции базы — либо оба действия, либо ни одного — и возвращаем код заказа.
5. Мы отправляем заказ поставщику. Если он недоступен, заказ уходит в очередь ретраев, а для вас просто остаётся в статусе processing.
6. Когда заказ разрешается, мы доставляем подписанный вебхук на ваш callbackUrl. Если удобнее опрашивать — есть и эндпоинт заказа.

Для самого каталога рабочая схема — гибридная: метаданные игр держите у себя и обновляйте по расписанию, товары читайте лениво и с коротким кэшем, а перед созданием заказа перечитывайте товар заново. Цены двигаются вместе с курсом и изменениями у поставщика, поэтому цена, закэшированная час назад, — это цена, которой вы можете уже не получить. Эндпоинты и окна кэша — на странице Каталог.

Чего этот API не делает

Сразу, потому что каждый пункт кому-то стоил спринта:

• Нет загрузки файлов. SKU, чья форма доставки требует скриншот или изображение, полностью исключены из B2B-каталога, а заказ по такому товару отклоняется.
• Нет sandbox на /b2b/*. Ключ с тестовым префиксом ведёт себя здесь ровно как боевой: настоящий каталог, настоящий баланс, настоящий поставщик. Прочитайте Авторизацию до того, как направите сюда тесты.
• Нет отмены заказа. Созданный заказ доходит до терминального статуса; вызова, который его откатит, не существует.
• Нет цены в запросе. Передать её бессмысленно — мы считаем цену на своей стороне каждый раз.
• Ничего, обращённого к покупателю. Ни хостед-чекаута, ни приёма платежей, ни уведомлений покупателю.

С чего начать

Читайте в этом порядке — интеграция соберётся без возвратов назад:

1. Быстрый старт — пять вызовов curl от пустого терминала до живого заказа.
2. Авторизация — заголовок, типы ключей и что на самом деле значат 401 и 403.
3. Каталог — игры, категории, товары и что хранить у себя.
4. Прямое пополнение по API — доставка по UID или Player ID, самая большая часть каталога.
5. Типы доставки — пять значений и что каждое требует от вас.
6. Заказы — статусы, частичная доставка и что значит «висит в processing».
7. Вебхуки — подписанный канал событий и как его проверять.
8. Идемпотентность и ошибки — как безопасно повторять запрос и как читать отказ.