Что такое APIStend

APIStend отвечает на запросы так же, как отвечают боевые API Bitrix24, Ozon Seller и Wildberries. Вы подменяете базовый адрес в своём коде — путь, HTTP-метод, заголовок авторизации и разбор ответа остаются прежними.

- curl https://api-seller.ozon.ru/v3/posting/fbs/list -H "Api-Key: $REAL"
+ curl http://localhost:8080/oz/v3/posting/fbs/list   -H "Api-Key: $STEND"

Задача, которую он решает

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

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

У Bitrix24 работает и адресация без префикса — /rest/… в корне стенда: портал сообщает приложению голый домен, и приложение склеивает адрес REST само.

Чем APIStend не является

• Не прокси и не кеш боевого API. Данных сервисов внутри нет вообще: ответы собираются из официальных спецификаций и детерминированного генератора.
• Не официальная песочница вендоров. Это независимый проект. APIStend не связан с ООО «1С-Битрикс», ООО «Интернет Решения» (Ozon) и ООО «Вайлдберриз»; названия сервисов используются для указания совместимости. Источники документации, лицензии и даты снимков перечислены в NOTICE.md репозитория.
• Не хранилище состояния. Успешный ответ — чистая функция от метода, сценария и объёма демо-данных. Созданная через мок сделка не появится в следующем списке; подробнее — в разделе Основные понятия.
• Не средство обхода лимитов и не источник боевых данных. В стенде нет ни одного реального заказа, товара и контакта.

Как это устроено

Каталог методов собирается из спецификаций сервисов: OpenAPI у Ozon и Wildberries, документация b24restdocs у Bitrix24, у которого OpenAPI нет. У каждой записи каталога хранится происхождение — откуда взят ответ, каким способом получен, ссылка на страницу документации и дата снимка. Ответ строится тремя ярусами по приоритету: пример из спецификации, генерация по схеме детерминированным филлером, а если схемы нет — пустой конверт сервиса, и метод честно помечается как незавершённый.

Шлюз поверх этого делает то, что делает боевой сервис: проверяет ключ, считает лимит по профилю конкретного сервиса, выдерживает задержку, при необходимости подменяет успех на сценарий ошибки и пишет вызов в журнал. Отдельная часть — события: они уходят в нативном формате каждого сервиса, с его политикой повторов и подписью, и доставляются на localhost разработчика через агент из npm-пакета apistend, без публичного адреса.

Принцип, который проверяется в ответах

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