Webhooki sklepów (e-commerce)
WooCommerce, Shoper, Shopify, Allegro i inne — URL webhooka, sekret, podpis HMAC, flow FV → KSeF.
Ostatnia aktualizacja: 1 września 2026 · wersja 1.0.0-rc40
Publiczne API (portal / ERP — nie sklep)
Webhook sklepu to inny kanał niż REST API /v1. Sklep wysyła JSON zamówienia na stały URL per firma; system tworzy fakturę VAT (szkic lub od razu w kolejce KSeF). Portal własny → POST /v1/invoices + opcjonalnie callbackUrl.
Konfiguracja (Zaplecze)
- Wybierz firmę → Zaplecze → zakładka Integracje.
- Skopiuj URL webhooka dla platformy (np. WooCommerce).
- Wklej ten sam sekret w sklepie i w polu „Sekret webhooka” w Zapleczu → Zapisz.
- Opcjonalnie: zaznacz „Automatycznie kolejkuj do KSeF po imporcie” — domyślnie wyłączone (najpierw sprawdź VAT w Fakturach).
URL ma postać: https://api.ksiegujesam.pl/integrations/{platforma}/{organizationId}/webhook — organizationId to ID firmy z GET /v1/me lub z adresu po zalogowaniu.
WooCommerce
- Endpoint: POST …/integrations/woocommerce/{orgId}/webhook
- Nagłówki: X-WC-Webhook-Signature (HMAC-SHA256 body, base64), X-WC-Webhook-Topic (np. order.updated).
- Sekret: ten sam co w Woo → Ustawienia → Zaawansowane → Webhooki.
- Statusy zamówień obsługiwane: processing, completed, on-hold — inne są pomijane.
- VAT pozycji: domyślnie 23% netto z line_items.total / quantity — zweryfikuj przed KSeF.
Inne platformy (skrót)
- Shoper — HMAC, nagłówki X-Webhook-Signature / X-Shoper-Signature.
- Shopify — X-Shopify-Hmac-Sha256, topic orders/create.
- BaseLinker, Allegro, PrestaShop, IdoSell, Magento, Sky-Shop, RedCart — token w X-Webhook-Token lub ?token= (ten sam sekret co w Zapleczu).
- Apilo, Sellasist — token jak wyżej.
Co się dzieje po webhooku
- Weryfikacja podpisu / tokenu — 401 przy złym sekrecie.
- Mapowanie nabywcy i pozycji z JSON zamówienia.
- Idempotencja po externalId (np. id Woo) — powtórny webhook nie duplikuje FV.
- Faktura trafia do /faktury; magazyn aktualizuje się wg polityki firmy.
- Gdy włączone auto-KSeF — kolejka wysyłki po utworzeniu FV.
API callbackUrl (portal, nie sklep)
Przy POST /v1/invoices możesz podać callbackUrl — po wystawieniu FV system robi POST invoice.created z nagłówkiem X-KS-Signature (HMAC-SHA256 surowego body kluczem API). To nie jest webhook Woo — patrz /integracja.
Zaplecze: KSeF, Dropbox, banking
VAT e-commerce / OSS (ViDA)
- Znaczniki JPK sprzedaży: WSTO_EE (sprzedaż na odległość UE), EE, SW (call-off — plan uchylenia od 2028-07 na rzecz TOOG).
- Projekt RM 2026-09: usprawnienie pakietu VAT e-commerce + ViDA cz. 1 — zasadniczo od 2027-01-01 (szersze OSS).
- Krajowe odliczenia VAT i JPK_V7 bez zmian w tej noweli — to sprzedaż UE / OSS, nie stawki 23%/8%/5%.
- Kalendarz: przypomnienia planowe w I 2027 i VII 2028. To nie doradztwo podatkowe.