Основные понятия

Семь понятий, вокруг которых устроен весь продукт. Разобравшись с ними один раз, дальше можно читать любой раздел справочника в произвольном порядке.

Аккаунт

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

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

Вторая песочница нужна тогда, когда работ две: одна под отлаживаемую интеграцию, другая под демонстрацию или под автотесты, которые сбрасывают данные. Ключи, вебхуки, свои моки и журнал запросов принадлежат песочнице и между ними не переносятся.

Песочница

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

Задержку и долю ошибок настраивают ползунками на экране «Ключи и токены», песочницы заводят и переключают в меню аккаунта, а объём данных меняют только через Management API. Фактическая задержка — минимум из настройки песочницы и задержки самого метода из каталога; заголовок X-Mock-Delay перебивает обе.

Объём данных

min, medium и full — размер каталога товаров песочницы: 100, 300 и 1000 артикулов. Он же служит солью детерминированного генератора, поэтому смена объёма меняет и сам набор: идентификаторы, суммы и названия из прошлых ответов перестают совпадать.

Каталог общий для всех песочниц и доступен только на чтение — поэтому создание песочницы ничего не копирует, а кеш ответов состоит из «методы × три объёма», а не «методы × количество аккаунтов».

В кабинете переключателя объёма сейчас нет: значение меняется через Management API (PATCH /api/v1/sandboxes/{id}).

Каталог товаров

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

Это и отличает стенд от песочниц самих площадок: там методы отвечают верно по форме, но про разные товары, и посчитать на них маржу, ДРР или «хватит на N дней» нельзя.

Ключи

Ключей два вида, и различаются они префиксом:

Полное значение показывается один раз — при создании. В базе лежит HMAC-SHA256 от ключа и его края: начало и хвост складываются в маску stend_sbx_7f3a••••••4c21, по которой ключ узнают в списке. Именно HMAC, а не argon2: ключ проверяется на каждом запросе к шлюзу, а argon2id сжёг бы весь бюджет задержки. Подбор здесь ни при чём — это 128 бит криптослучайности, а не пароль человека.

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

Поле rotationDays (по умолчанию 90) — срок напоминания о замене, а не срок жизни: сам по себе ключ не протухает. Отзыв необратим и подтверждается вводом названия ключа — проверка есть и на сервере, а не только в диалоге. Тарифных квот на количество ключей и запросов к мок-шлюзу у продукта нет. Технические ограничения есть у другого: Management API пропускает 240 запросов в минуту на ключ или сессию (выгрузка журнала — шесть в минуту), а песочниц в аккаунте может быть не больше двадцати.

Ключ шлюз принимает там же, где его ждёт боевой сервис: X-Mock-Key работает всегда, Authorization — как у Wildberries, Client-Id с Api-Key — как у Ozon, путь /rest/{user_id}/{code}/ и параметр auth= — как у Bitrix24, включая ключ внутри JSON-тела.

Каталог методов

Каталог — список методов всех сервисов стенда, собранный из их спецификаций и документации. У каждой записи хранится происхождение, и оно видно и в каталоге, и в заголовках ответа:

• источник ответа — example (пример из спецификации), schema (сгенерирован по схеме) или generic (схемы нет, отдан пустой конверт сервиса);
• способ получения — spec, mirror или parsed;
• готовность мока — ready, updating или planned;
• ссылка на страницу документации и дата снимка спецификации.

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

Сценарии ответов

Сценарий выбирается заголовком X-Mock-Scenario и решает, каким будет ответ: успешным или конкретной ошибкой в формате этого сервиса.

Неизвестное значение заголовка трактуется как success. Сценарий, который в итоге отработал, всегда возвращается в X-APIStend-Scenario — включая случай, когда шлюз подменил ваш success на rate_limit по исчерпанию лимита или на server_error по доле случайных ошибок.

Overlay и сброс

Базовый набор демо-данных общий для всех песочниц и доступен только на чтение. Личное — созданное, изменённое и удалённое вами — по замыслу модели данных живёт отдельным слоем поверх него, overlay. Отсюда и устройство сброса: POST /api/sandbox/reset (кнопка «Сбросить сейчас» на экране «Ключи и токены») удаляет overlay песочницы и обновляет отметку времени последнего сброса. Ключи, вебхуки и свои моки сброс не трогает.