SDK Corp-Merch для Польша

Команды установки

Node.js: npm install @corp-merch/sdk. Python: pip install corp-merch (Python 3.10+). PHP: composer require corp-merch/sdk (PHP 8.1+). Все пакеты подписаны; lockfile публикуются. Minor — еженедельно; semver-strict — никаких breaking changes вне major-релизов.

FAQ

Готовые клиенты под язык программирования

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

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

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

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

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

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

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

Если пакет обновляется в середине спринта, безопаснее оставить старую версию в основной ветке и перейти на новую отдельным pull request. Тогда регрессия видна сразу в тестах, а не в проде. Мы добавляем в каждый релиз список изменений, по которому видно, какие поля ответа добавились и какие методы появились.

Пакеты работают с любым HTTP-клиентом, если вы предпочитаете писать запросы сами: подпись и разбор ответа — единственное, что стоит перенести из нашего кода. Остальное вы делаете своим кодом и своей политикой повторов. Такой вариант реже ломается при обновлении зависимостей.

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

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