Интеграция и API
Каталог, заказ, коды, баланс и события — запросами, а не письмами. Здесь то, что построено и открыто снаружи, и то, что стоит знать про автовыдачу на маркетплейсе.
Что умеет наш API сегодня
Каталог с ценами и наличием
Позиции, оптовые цены, наличие и — когда сетка наполнена — ступени объёма приезжают одним ответом. Весь прайс целиком выгружается файлом из того же снимка: расхождения между файлом и API нет по построению.
Заказ, который не выполнится дважды
Повтор запроса с тем же ключом идемпотентности отдаёт ответ первого заказа, а не создаёт второй. Оборвалась сеть на середине — просто повторите: списание останется одно.
Коды забираются запросом
Выданные коды лежат у заказа и перечитываются сколько угодно раз. Ответ переживает наш перезапуск дословно — код не «показывается один раз».
События вебхуками
Подписка на события заказа и баланса, подпись запроса, ретраи и повтор события по требованию. Опрашивать нас в цикле не нужно.
Баланс и журнал движений
Остаток и каждое движение — пополнение, списание за заказ, возврат — видны запросом и совпадают с тем, что показывает кабинет.
Песочница
Отдельный ключ проходит тот же путь на отдельном кошельке и фиктивном поставщике: те же проверки, тот же конверт ответа, та же идемпотентность, коды с меткой TEST-. Ничего вашего не тратится.
Что открыто снаружи СЕГОДНЯ, а что ещё нет
Снаружи открыт ПЕСОЧНЫЙ контур: с песочным ключом весь путь — каталог, заказ, коды, журнал — проходится целиком и прямо сейчас, ничего не тратя. Боевого адреса пока нет: он приедет вместе с доменом, и до тех пор боевые ключи никуда не ходят.
Мы пишем это на первой же полке про интеграцию, а не мелким шрифтом внизу, потому что для вас это вопрос планирования: код под наш API можно написать и проверить уже сегодня, а поставить его на боевой поток — после нашего объявления. Обещать «всё работает» и получить вопрос «почему боевой ключ отвечает ошибкой» — худший способ начать.
Как подключаются
От нас приходит одним сообщением четыре вещи: базовый адрес, ключ доступа, набор прав этого ключа и список адресов, с которых он принимается, если вы его задали. Дальше логин не нужен — весь путь проходится по документации.
Начинать имеет смысл с песочного ключа: он позволяет пройти каталог, заказ, коды и журнал целиком, ничего не потратив, и убедиться, что ваша сторона обрабатывает наши ответы так, как вы задумали.
Автовыдача на Яндекс.Маркете: что важно знать
Готовой связки с Маркетом мы не даём — выдачу вы делаете своим кодом. Но контракт Маркета устроен так, что одна неверная строка стоит потока заказов, и знать про неё лучше заранее, чем после.
Механизм
Модель DBS: Маркет присылает вам вебхук о заказе, вы передаёте код методом deliverDigitalGoods, и Маркет сам доставляет ключ покупателю. Так выдаются подтипы EMAIL и ACTIVATION_CODE; STEAM_GIFT и CHAT этим методом не выдаются — там смена статуса заказа.
Сроки, которые вы обязаны держать
Ответ на вебхук — 200 не позже 10 секунд, на проверочный PING — не позже секунды. Сам код надо передать в течение 30 минут после перехода заказа в обработку. Это значит, что принимать вебхук и выдавать код должны разные части вашей системы.
Ошибка, которая стоит дороже всех
Ответ 400 от вас — и Маркет прекращает ретраи по этому заказу НАВСЕГДА. На любой временный сбой отвечать надо 500, никогда 400. Заказы при этом перестают доходить молча: ошибок в вашем логе не будет.
Один заказ — один комплект
Маркет может прислать вебхук об одном заказе дважды. Идентификатор заказа Маркета должен быть уникальным ключом на вашей стороне, иначе покупатель получит второй код за те же деньги — уже ваши.
Частые вопросы
Можно ли уже сейчас пустить через вас боевой поток?
Нет. Снаружи открыт песочный контур — весь путь проходится целиком, но на песочных деньгах и фиктивном поставщике. Боевой адрес приедет вместе с доменом, и мы объявим об этом отдельной строкой в журнале изменений. Написать код и проверить его можно уже сегодня.
Что нужно, чтобы начать подключение?
Ключ доступа от нас и наша публичная документация. Логин и переписка с менеджером в этом пути не участвуют: каталог, заказ и коды проходятся по документации. Права ключа и список разрешённых адресов приходят вместе с ним — машинной ручкой «какие у меня права» они не проверяются, поэтому сохраните их рядом с ключом.
Можно ли всё проверить, не тратя деньги?
Да, для этого есть песочный ключ. За ним стоит отдельный кошелёк, фиктивный поставщик и коды с меткой TEST-. Путь заказа тот же, что боевой: те же проверки, тот же конверт ответа, та же идемпотентность и те же события.
Что будет, если мой запрос оборвался и я не знаю, прошёл ли заказ?
Повторите его с тем же ключом идемпотентности. Мы отдадим ответ первого заказа, а не создадим второй, и списание останется одно. Отдельно узнать состояние заказа можно запросом по его номеру — там же лежат и выданные коды.
Как я узнаю, что заказ выдан, если не опрашивать вас в цикле?
Подпиской на события: мы присылаем их вебхуком, подписываем запрос и повторяем доставку при сбое. Пропущенное событие можно запросить повторно.
У вас есть готовый коннектор к Яндекс.Маркету или другой площадке?
Нет. Мы отдаём каталог, заказ и коды по API, а связку с конкретной площадкой вы делаете своим кодом. Что именно важно учесть в контракте Маркета — написано выше на этой странице.
Вопросы
Как устроены партии, выдача, баланс и подключение по ключу — короткие ответы без переговоров.
Вопросы