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