Сеть реселлеров превращает ваш магазин в оптовика: другие магазины, боты и маркетплейсы покупают у вас коды и пополнения и перепродают их. Они подключаются через API, отправляют тысячи заказов и ждут одинакового результата каждый раз.
Разберём, из чего состоит API для реселлеров цифровых товаров, на примере API Kavia Commerce. Кабинет и API для реселлеров входят в тарифы Pro и Max.
Ключи: показываются один раз, хранятся как хеш
Каждый партнёр получает свой API-ключ. Ключ показывается один раз при создании и хранится только в виде хеша, как пароль. Даже при утечке базы ключами из неё воспользоваться нельзя.
Каждый ключ можно ограничить списком разрешённых IP-адресов, и у каждого свой лимит запросов: ошибка одного партнёра не замедлит остальных.
Подписанные запросы
Одного ключа мало: любой, кто увидит запрос в логах, сможет его повторить. Запросы к Kavia Commerce подписываются HMAC — стандартным способом доказать, что сообщение отправил владелец ключа и его не меняли (RFC 2104). В каждом запросе также есть метка времени и одноразовый nonce, поэтому старый запрос повторно не пройдёт.
Идемпотентные заказы: правило, которое экономит деньги
Сети сбоят. Партнёр отправил заказ, соединение оборвалось до ответа, и его система повторяет запрос. Без защиты это два заказа и два списания.
Решение — идемпотентность: партнёр передаёт свой номер заказа в каждом запросе. В Kavia Commerce один externalOrderId — один заказ. Повтор с тем же номером возвращает исходный заказ, а не создаёт новый. Тот же принцип используют платёжные API, см. объяснение Stripe об идемпотентных запросах.
Упрощённо заказ выглядит так:
POST /v1/orders с productId, quantity и externalOrderId "A-77812"
Ответ: статус COMPLETED, сумма в виде десятичной строки, валюта и коды.
Суммы передаются десятичными строками, а не числами с плавающей точкой, поэтому 11.20 остаётся 11.20.
Ценовые группы и оптовые заказы
Партнёры платят по-разному. Ценовые группы позволяют дать крупному реселлеру другой прайс, чем маленькому, без отдельных каталогов. Оптовые заказы позволяют купить много кодов одним запросом.
Вебхуки: сообщить партнёру, что произошло
Пополнение может занять несколько секунд, и иногда оно не проходит. Чтобы партнёрам не приходилось постоянно опрашивать API, платформа отправляет вебхуки: order.created, order.completed, order.failed и order.refunded. При неудачном заказе резерв на балансе партнёра снимается.
Тестовые ключи
Партнёрам нужно всё проверить, прежде чем тратить деньги. Sandbox-ключи позволяют делать тестовые заказы и получать вебхуки, не трогая настоящий склад.
Попробуйте
На странице живых демо есть интерактивное демо API реселлеров прямо в браузере, а на странице платформы — настоящий запрос и ответ с примерными значениями. В демо-магазине видно, из какого каталога заказывают партнёры. Чтобы проверить само API, запросите sandbox-ключ. Как защищены ключи, балансы и заказы — на странице безопасности.
Вопросы
Что будет, если партнёр отправит один заказ дважды?
Ничего лишнего. В каждом заказе есть externalOrderId партнёра, и один externalOrderId — это один заказ. Повтор возвращает исходный заказ, второе списание не происходит.
Как защищены ключи API?
Ключ показывается один раз и хранится только как хеш. Каждый ключ можно ограничить списком IP и лимитом запросов, а каждый запрос подписывается HMAC с меткой времени и nonce.
Можно дать разным реселлерам разные цены?
Да. Ценовые группы позволяют назначить каждому партнёру свой прайс без отдельных каталогов.
В каком тарифе есть API для реселлеров?
Кабинет и API для реселлеров входят в Kavia Pro и Kavia Max.