REST API для закупок в Польше
Программный доступ к Corp-Merch — размещение заказов, синхронизация каталога, получение webhook-событий. JSON через HTTPS, авторизация Bearer, SLA 99,95%.
Аутентификация и лимиты
OAuth 2.0 client credentials или долгоживущие Bearer-токены (ротация каждые 90 дней). Базовый URL: https://api.corp-merch.com/v1. Лимит: 600 запросов/мин на токен, burst 60 запросов/сек. Все payload — UTF-8 JSON; timestamp ISO 8601. Ошибки по RFC 7807 (application/problem+json).
Обзор endpoint-ов
POST /v1/orders — отправить заказ. GET /v1/catalog — получить локализованные SKU (цены в EUR/PLN с включённым VAT 23%). GET /v1/orders/{id} — статус заказа с tracking. POST /v1/webhooks — зарегистрировать callback URL для order.shipped, invoice.issued (via KSeF), invoice.paid. Полная OpenAPI 3.1 на /v1/openapi.json.
Соответствие и выставление счетов в Польше
Каждый заказ автоматически генерирует счёт VAT 23% через KSeF (обязательно в Польше). XML доступен через GET /v1/invoices/{id}; подписан QES по eIDAS. Архивация 10 лет. Webhook invoice.issued срабатывает в течение 60 секунд после подтверждения KSeF. Хаб Варшава обрабатывает API-заказы в день получения, если получены до 14:00 по местному времени.
FAQ
Какая аутентификация используется в API?
OAuth 2.0 client_credentials с возвратом Bearer-токена (срок жизни 1 час). Долгоживущие токены для server-to-server с 90-дневной ротацией. Также поддерживаем mTLS для enterprise.
Как протестировать перед production?
Sandbox на https://api.sandbox.corp-merch.com — полный паритет функциональности, тестовый каталог, mock-счета. Webhook-события воспроизводимы за последние 30 дней из dashboard.
Какой SLA?
99,95% uptime на endpoint v1 (измерение ежемесячное). Status page на status.corp-merch.com с RSS/webhook-подписками на инциденты.
Соответствуют ли счета законодательству Польша?
Да — все счета через KSeF с VAT 23%. Формат соответствует национальной схеме (FatturaPA / SAF-T PT / KSeF / Facturae), валидируется на стороне сервера до отправки.
Как обрабатываются retry webhook-ов?
Экспоненциальный backoff: 1m, 5m, 15m, 1h, 6h, 24h. После 6 неудач подписка ставится на паузу, и мы оповещаем по email. Подписаны HMAC-SHA256 в заголовке X-Corp-Signature.
Как устроен программный доступ
Программный доступ к каталогу и заказам сделан так, чтобы в него можно было перенести ручной процесс без его переписывания. Базовый адрес один, авторизация выдаётся под конкретного клиента, а не под сайт, поэтому у каждого закупщика своя пара ключей и своя история запросов. Ответы приходят в UTF-8 JSON, время в теле ответа указано в формате ISO 8601, а коды ошибок соответствуют RFC 7807.
Каталог отдаёт позиции, уже локализованные под Польшу: цены в злотых с НДС 23 процента, а для компаний с действующим номером НДС применяется обратное начисление в рамках ЕС. Заказ создаётся одной операцией и проходит обычный производственный цикл, поэтому сроки в интерфейсе совпадают со сроками в бухгалтерии и логистике. Вебхуки приходят на адрес, который вы указываете сами, и подписываются, чтобы вы могли отличить настоящее событие от чужого запроса.
На страницах ниже описаны отдельные операции: аутентификация и лимиты, чтение каталога, создание заказа, получение статуса и доставки, подписка на вебхуки, выставление счетов и журнал изменений. Читайте их по порядку, если настраиваете доступ впервые: первые две страницы отвечают на вопросы про токены и квоты, остальные можно открывать по мере надобности.
Перед запуском в бой заведите тестовый контур с теми же данными, что и в рабочем, и прогоните полный цикл: чтение каталога, черновик заказа, подтверждение, отмена до старта производства. Такой прогон занимает около часа и снимает почти все вопросы на этапе первой живой отгрузки, когда каждый час промедления уже стоит денег.
Отдельно про квоты. Ограничение в 600 запросов в минуту на токен рассчитано на пакетную синхронизацию каталога и на операции закупщика одновременно. Если у вас тяжёлая интеграция, разнесите чтение каталога и запись заказов по разным токенам: тогда всплеск чтения не съест квоту на оформление, и наоборот.
Документация к каждой операции возвращается в одном формате: описание, параметры, пример запроса, пример ответа и список кодов ошибок. Примеры приведены на реальных значениях из польской локали. Если примера не хватает, напишите — мы добавляем его в ту же страницу, чтобы документация оставалась в одном месте.
Полезно держать в интеграции одну переменную со средой. Меняете адрес — меняете одно значение, а не десять строк в коде. Пакет клиента читает её из окружения, и это позволяет прогнать тестовый сценарий на тестовом контуре, не трогая рабочий.
Отдельно про журналирование: мы не пишем в лог содержимое заказов и персональные данные, только идентификатор операции и результат. Этого достаточно, чтобы связать заказ в системе клиента с заказом у нас, и при этом лог остаётся пригодным для хранения.
Документация API — все эндпоинты
У каждого эндпоинта есть своя страница с методом, параметрами и ответом. Этот список ведёт от общего описания к конкретному вызову.