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.