Платформа HstockPlus: как заказы, выполнение заказов и API на самом деле работают вместе

На этой странице описано, как маркетплейс работает как система: какие в нём роли, как проходит заказ и что предоставляет API. С этой страницы ничего не продаётся.

Два каталога, а не один

На платформе два вида товаров, и они ведут себя настолько по-разному, что считать их одним целым — значит создавать себе проблемы.

Товарные позиции — это цифровые товары, продаваемые единицами из запасов продавца: аккаунты, почтовые ящики, прокси, ключи. Покупателям в любой момент видно примерно семнадцать тысяч позиций, взятых из более крупного каталога, который включает черновики, позиции, ожидающие одобрения, и позиции, отключённые продавцом. Они сгруппированы по категориям и подкатегориям, помечены тегами для фильтрации, а цена задаётся для каждого варианта, а не для позиции в целом, поэтому одна позиция может иметь несколько вариантов покупки по разным ценам.

Сервисы продвижения — это товары, основанные на количестве: вы заказываете определённое число подписчиков, просмотров или комментариев по ссылке. Активных примерно тридцать тысяч. У них своя категоризация и свой набор тегов, и они не учитываются в лимите товарных позиций продавца.

Продавцов по активному каталогу — несколько сотен, при этом около полутора тысяч аккаунтов имеют роль продавца, распределённых примерно по пятистам шестидесяти магазинам.

Роли и что каждой доступно

Существует три роли, и они дополняют друг друга, а не исключают: один аккаунт может быть одновременно и покупателем, и продавцом.

• Покупатели просматривают товары, оформляют заказы, имеют баланс на сайте, отслеживают заказы и открывают обращения в поддержку.
• Продавцы управляют позициями и запасами, обрабатывают заказы, настраивают купоны и запрашивают выплаты. Профиль продавца можно сделать публичным, чтобы покупатели могли просматривать все предложения продавца в одном месте.
• Администраторы одобряют продавцов и позиции, решают споры и управляют настройками, от которых зависит поведение платформы.

Сейчас требуется одобрение продавца, и оно распространяется и на API, и на интерфейс: если аккаунт продавца не одобрен, он получает явный ответ об ожидании одобрения, а не пустой каталог. Это важно различать, когда интеграция возвращает пустой результат.

Продавцы распределены по одному из пяти уровней, рассчитываемых на основе атрибутированных продаж за последние двенадцать месяцев. Уровень не просто для галочки. Он определяет, сколько платформа ждёт перед автоматическим высвобождением средств, и участвует в расчёте лимита позиций.

Как движется заказ

Состояние заказа и состояние оплаты отслеживаются отдельно, и оба важны при чтении API.

Состояние заказа проходит через ожидание, обработку, выполнение и затем, возможно, возврат, при этом отмена и ошибка — конечные состояния. Состояние оплаты — отдельное поле со своими значениями: выполнено, частично, возвращено, не удалось, ожидает и в обработке. Один момент, если вы пишете фильтр: состояния оплаты «оплачено» не существует. Запрос по нему вернёт пустой результат, что выглядит как пустая выдача, а не как ошибка в запросе.

Способ выполнения зависит от типа позиции. Автоматические позиции и позиции с запасами передают товар, который платформа уже хранит. Ручные позиции — это те, где нужны действия продавца или его программного обеспечения, и именно для них предназначен API выполнения.

Как только покупатель получил заказанное, открывается гарантийный период. Он измеряется в часах и отсчитывается с момента доставки, а не оплаты, с минимальным значением по всей платформе и индивидуальными настройками продавца сверху. В течение этого периода покупатель может открыть обращение или спор; за его пределами путь через спор закрыт. Средства высвобождаются продавцу либо когда покупатель подтверждает получение, либо когда истекает таймер автоподтверждения для уровня продавца — что наступит раньше, а активный спор приостанавливает высвобождение.

API и одно различие, которое важнее всего

Есть два API, оба аутентифицируются по ключу.

API для покупателей следует широко распространённой панельной конвенции: один эндпоинт с параметром action. Стандартные действия реализованы полностью, поэтому существующие панельные инструменты работают с ним: services для списка доступного, add для размещения заказа, status для проверки, balance, refill и cancel. Сверх этого добавлены действия, которых конвенция не определяет: categories и subcategory_info для навигации по таксономии, products и shops, allowcancel, inventory для проверки запасов, а также полный набор действий для SMS-верификации: проекты, страны, заказ номера и опрос кода. Воспринимайте это как стандартную конвенцию плюс расширения, а не как точную копию: стандартные вызовы работают без изменений, а расширения — это то, где живут специфические возможности платформы.

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

• Список заказов — это чтение. Оно ничего не закрепляет. Два воркера, опрашивающие его, получат один и тот же заказ, и оба попытаются его выполнить.
• Вытягивание заказов — это закрепление. Оно переводит каждый заказ из ожидания в обработку условной записью и возвращает только те заказы, чья запись действительно выиграла. Если два воркера вытягивают одновременно, каждый получает непересекающийся набор.

Всё, что выполняет заказы автоматически, должно вытягивать, а не читать список. Чтение используйте для дашбордов и сверки, где увидеть один и тот же заказ дважды — не проблема.

Ещё три детали сэкономят вам день. Вытягивание возвращает только позиции ручного выполнения, так что автоматические позиции и позиции с запасами там не появятся. Партия по умолчанию — сто заказов, максимум — пятьсот. И вытянутый заказ не предлагается снова примерно полчаса: это намеренный запас прочности. Если ваш воркер упадёт после вытягивания, заказ вернётся сам, но не мгновенно.

Полная документация по обоим API — в документации API покупателя и документации API продавца.

Платежи и балансы

На платформе действует внутренний баланс, через который проходит большинство операций. Покупатели пополняют его и тратят с него, возвраты зачисляются на него, и именно с него оплачивается большинство заказов. Для пополнения поддерживаются и криптовалюта, и обычные платёжные каналы: одни расчёты проходят напрямую, другие — через платёжного провайдера.

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

Поддержка и споры

Поддержка работает через систему обращений, общую для всех трёх ролей: покупатель, продавец и поддержка могут находиться в одном треде, а не в трёх разговорах, которые никогда не встречаются. Обращения содержат классификацию проблемы, и продавец может закрыть его, заменив доставленный товар, вернув за него деньги или отклонив претензию.

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

Что работает по расписанию

Некоторые вещи происходят без чьего-либо участия, и об интеграции легче рассуждать, зная о них: средства автоподтверждаются и высвобождаются после задержки по уровню продавца; спор, оставленный без внимания после закрытия всех его обращений, решается в пользу продавца через фиксированное число дней; избранные размещения истекают по ежедневной задаче; одобренные рекламные публикации перепроверяются еженедельно; а тексты позиций сканируются партиями на предмет правил о контактах вне платформы.

Ни одно из этих событий не анонсируется через API. Если ваша сверка видит, что заказ сменил состояние без вызова с вашей стороны, — обычно причина в одном из них.

Начало работы

1. Зарегистрируйтесь, затем запросите одобрение продавца, если планируете продавать. Одобрение распространяется и на API, и на интерфейс.
2. Создайте позиции или импортируйте сервисы продвижения оптом из настроенного вышестоящего провайдера, а не по одному.
3. Сгенерируйте ключ API и перед всем остальным подтвердите свою роль, вызвав эндпоинт профиля.
4. Если вы выполняете заказы вручную, сразу стройте интеграцию на эндпоинте вытягивания. Переходить со списка на вытягивание после того, как вы отправили дублирующиеся поставки, — день куда хуже, чем прочитать этот абзац.
5. Осознанно задавайте гарантийные часы для каждой позиции. Это часы, по которым работает вся защита покупателя на платформе, и они начинаются с момента доставки.