REST API dla procurementu w Polsce
Programowy dostęp do Corp-Merch — składanie zamówień, synchronizacja katalogu, odbiór zdarzeń webhook. JSON przez HTTPS, autoryzacja Bearer, SLA 99,95%.
Uwierzytelnianie i limity
OAuth 2.0 client credentials lub długoterminowe tokeny Bearer (rotacja co 90 dni). Bazowy URL: https://api.corp-merch.com/v1. Limit: 600 req/min na token, burst 60 req/sek. Payloady UTF-8 JSON; znaczniki czasu ISO 8601. Błędy zgodne z RFC 7807.
Przegląd endpointów
POST /v1/orders — złóż zamówienie zakupu. GET /v1/catalog — pobierz SKU zlokalizowane dla Polski (ceny w PLN z VAT 23%). GET /v1/orders/{id} — status zamówienia z trackingiem. POST /v1/webhooks — zarejestruj URL callback dla zdarzeń order.shipped, invoice.issued (via KSeF), invoice.paid. Pełna specyfikacja OpenAPI 3.1 na /v1/openapi.json.
Zgodność i fakturowanie w Polsce
Każde zamówienie automatycznie generuje fakturę VAT 23% via KSeF (obowiązkowe w Polsce od 2026). XML dostępny przez GET /v1/invoices/{id}; podpisany QES wg eIDAS. Archiwizacja 10 lat. Webhook invoice.issued odpala się w 60 sekund po potwierdzeniu z KSeF. Hub w Warszawa przetwarza zamówienia API tego samego dnia, jeśli otrzymane do 14:00 czasu lokalnego.
FAQ
Jakiej autoryzacji używa API?
OAuth 2.0 client_credentials zwracający token Bearer (1 godzina ważności). Tokeny długoterminowe dla server-to-server z 90-dniową rotacją. Wspieramy też mTLS dla klientów enterprise.
Jak testować przed produkcją?
Sandbox na https://api.sandbox.corp-merch.com — pełna parytetowość, przykładowy katalog, mockowe faktury. Zdarzenia webhook odtwarzalne dla ostatnich 30 dni z poziomu dashboardu.
Jakie SLA?
99,95% uptime na endpointach v1 (pomiar miesięczny). Status page na status.corp-merch.com z subskrypcjami RSS/webhook.
Czy faktury są zgodne z polskimi przepisami?
Tak — wszystkie faktury przez KSeF z VAT 23%. Format FA(3) XML zgodny z KSeF, walidowany po stronie serwera przed wysłaniem.
Jak obsługiwane są retry webhooków?
Backoff wykładniczy: 1m, 5m, 15m, 1h, 6h, 24h. Po 6 niepowodzeniach subskrypcja jest pauzowana, wysyłamy alert e-mail. Podpisane HMAC-SHA256 w nagłówku X-Corp-Signature.