Integracja sklepu internetowego z enova365 - REST API i praktyka

Czym jest enova365

ERP od krakowskiej Sonety. Modułowy - handel, magazyn, finanse, kadry, projekty, każdy moduł osobno. Wersja chmurowa (enova365 BIZNES) i on-premise. Aktywnie rozwijany, regularne aktualizacje.

Mocne strony jako baza dla sklepu B2B:

• Czyste REST API z OAuth2
• Solidny model cenowy (porównywalny z XL)
• Aktualne stawki VAT, e-Faktura (KSeF) - wbudowane
• Wsparcie dla pracy w chmurze (mniej problemów infrastrukturalnych)

Słabsze strony:

• Mniejszy rynek wdrożeniowców e-commerce specjalizujących się w enova niż w XL
• Mniej gotowych konektorów do platform e-commerce - częściej custom

REST API enova365

Endpoint base'owy: https://api.enova365.cloud/{tenant}/{wersja}/... (lub on-premise - adres serwera klienta).

Autoryzacja: OAuth2 Client Credentials Flow. Sklep / middleware dostaje client_id + client_secret od klienta enovy, wymienia na token, używa do każdego wywołania.

Format: REST + JSON. Endpointy nazwane po modułach enovy (/Handel/Kontrahenci, /Handel/Towary, /Handel/Dokumenty).

Limity:

• 60 req/min na konto (domyślnie, podniesione w SLA)
• Paginacja po 100/250/500 zależnie od endpointa
• Webhooks - TAK, na zmiany kluczowych encji (zmiana stanu, cennika, dokumentu)

To różnica jakościowa wzgl. GT / XL. Webhooks oznaczają, że nie musisz pollować - enova powiadamia.

Architektura wdrożenia

[Sklep Magento / Shopware]
        |
        | REST
        v
[Middleware - Symfony lub Node.js]
        |
        +--- REST + OAuth2 do enova365
        +--- Redis (cache, kolejki)
        +--- Webhooks listener z enovy

Middleware potrzebny dla typowych funkcji (kolejki, cache, idempotencja). Ale prostszy niż dla XL - nie musimy obchodzić timeoutów ani problemów SOAP-u.

Bezpośrednie połączenie sklep ↔ enova ma sens dla małych sklepów (do ~3k SKU). Powyżej - middleware ratuje skórę przy złożonych transformacjach i monitoringu.

Co synchronizujemy i jak

Towary (/Handel/Towary):

• enova → sklep, batch w nocy + delta przez webhook
• Pełna synchronizacja 50k SKU: ~1.5h (znacznie szybciej niż XL)
• Atrybuty filtrowalne - enova ma „cechy" towaru, sensowny model

Kontrahenci (/Handel/Kontrahenci):

• enova → sklep on-demand (po NIP) + okresowe synchro nowych
• Klient B2B rejestruje się w sklepie → middleware sprawdza NIP w enova → tworzy konto lub aktywuje

Ceny (/Handel/Cenniki):

• enova ma osobny endpoint do kalkulacji ceny dla kontrahenta - wykorzystujemy
• Cache 10-15 min, klucz (kontrahent_id, sku, ilosc)
• Webhook na zmianę cennika → invalidacja cache

Stany magazynowe (/Handel/Stany):

• Webhook + delta polling co 2-5 min
• Pull on-demand dla konkretnego SKU
• Cache 30s

Zamówienia (/Handel/Dokumenty/ZK lub bezpośrednio FS):

• Sklep → enova z idempotencyjnym Symbol (np. WEB-2026-000123)
• enova zwraca pełen Dokument z numerem nadanym, statusem, kosztem dostawy

Faktury:

• enova generuje, middleware odbiera webhook, pobiera PDF, zapisuje w storage sklepu
• E-Faktura (KSeF) - obsługiwana natywnie w enova, fakturę dostaje klient z KSeF, sklep tylko pokazuje numer

Cenniki w enova - co realnie dostajesz

enova ma rozbudowany silnik cen, porównywalny z XL:

• Cenniki indywidualne (per kontrahent)
• Cenniki grupowe (per grupa)
• Progi ilościowe (od 100 szt. cena X)
• Rabaty stałe i procentowe
• Promocje czasowe
• Cenniki w walutach
• Logika hierarchiczna (najpierw indywidualny, potem grupowy, potem promocyjny - konfigurowalna)

Sklep nie liczy ceny lokalnie. Zawsze pyta enovę.

Limity kredytowe i blokady

enova ma natywne wsparcie dla limitów kredytowych kontrahenta:

• Saldo bieżące (suma niezapłaconych faktur)
• Limit kredytowy (kwota maksymalna)
• Saldo + limit razem decydują o blokadzie

Endpoint /Handel/Kontrahenci/{id}/Saldo zwraca aktualne wartości. Sklep waliduje przed dopuszczeniem do checkoutu z formą „przelew z terminem".

W praktyce robimy walidację dwustopniową:

1. Soft check w koszyku (informacja: „uwaga, przekroczysz limit o X zł")
2. Hard check przy potwierdzaniu zamówienia (enova zwraca błąd, blokada)

Najczęstsze problemy

1. Wersje enovy - różnice między wydaniami. enova wydaje co kwartał. Aktualizacja u klienta to często okazja do zmiany pól w API. Testy integracyjne przy każdej aktualizacji.

2. Cloud vs. on-premise. Enova w chmurze Sonety ma stałe IP i dostęp. On-premise - często za firewall klienta, wymaga VPN lub IP whitelisting. Ustalanie tego trwa.

3. Webhooki z opóźnieniem. W godzinach szczytu webhook może mieć 30 s opóźnienia. Dla większości scenariuszy ok, dla rezerwacji koszyka - uzupełniamy pull on-demand.

4. Mapowanie kategorii i cech. enova ma model „grupy towarów" i „cechy" - sklep ma kategorie i atrybuty. Mapowanie 1:1 rzadko działa.

5. KSeF i faktury. Od 2026 obligatoryjne KSeF dla B2B. enova obsługuje natywnie, ale sklep musi pokazać klientowi prawidłowo numer KSeF + ewentualnie PDF (wizualizacja).

Gotowy konektor czy własna integracja

To pierwsza decyzja, jaką podejmiesz, i ta, która najbardziej zmienia budżet. Na rynku są trzy drogi.

Nie kupuj konektora, zanim nie sprawdzisz jednej rzeczy: czy obsługuje cenniki kontraktowe per kontrahent. To jest w B2B moment, w którym większość gotowych rozwiązań się kończy. Konektor zaprojektowany pod sklep B2C zna jedną cenę katalogową i ewentualnie rabat procentowy. Twoi kontrahenci mają wynegocjowane ceny na poziomie pozycji, czasem progowe, czasem czasowe.

Sprawdzian jest prosty i zajmuje jedno spotkanie: weź trzech najbardziej nietypowych kontrahentów i poproś dostawcę konektora, żeby pokazał, jak ich cennik trafi na sklep. Jeśli odpowiedź brzmi „to dopiszemy", jesteś już w wariancie drugim, tylko jeszcze o tym nie wiesz.

Czego dopilnować przed startem wdrożenia

Kolejność, w jakiej to sprawdzam, zanim ktokolwiek napisze linijkę kodu:

• Czy enova stoi w chmurze Sonety, czy on-premise za firewallem klienta
• Która wersja i kto po stronie klienta decyduje o terminie aktualizacji
• Czy licencja obejmuje moduł API - to osobna pozycja, nie zawsze wykupiona
• Kto jest właścicielem danych produktowych: enova czy PIM
• Jak wyglądają cenniki kontraktowe i czy da się je wyciągnąć jednym zapytaniem
• Czy limity kredytowe mają blokować koszyk, czy tylko ostrzegać
• Kto po stronie klienta odbierze testy i ma prawo powiedzieć „działa"

Ostatni punkt wygląda na miękki, a wywraca najwięcej projektów. Integracja z ERP dotyka księgowości, handlowców i magazynu naraz. Bez jednej osoby z prawem decyzji uzgadnianie mapowań potrafi trwać dłużej niż samo wdrożenie.

Koszt i czas

Czas:

• MVP (produkty + ceny + stany): 4-6 tygodni
• Pełna integracja (z zamówieniami, dokumentami, limitami kredytowymi): 10-14 tygodni
• Stabilizacja: 3-5 tygodni

Koszt:

• Wdrożenie: 70-160 tys. zł
• Licencje enova (po stronie klienta) - moduł handlowy + API: zależnie od konfiguracji
• Utrzymanie: 10-25 tys. zł rocznie

Szybciej niż XL, drożej niż Subiekt GT, znacznie taniej niż SAP. Dla większości polskich średnich B2B - najlepszy stosunek do funkcjonalności.

Kiedy enova ma sens nad XL czy GT

Nad GT - gdy:

• Skala rośnie powyżej możliwości GT (>15k SKU + 200+ kontrahentów)
• Potrzebujesz REST + webhooki
• Chcesz chmurową architekturę

Nad XL - gdy:

• Twoja firma startuje od zera (greenfield ERP)
• Cenisz nowoczesny API i krótszy time-to-integration
• Skala 5-80 M zł obrotu (XL od 80 M wzwyż jest mocniejszy)
• Nie potrzebujesz głębokiej customizacji ERP po stronie procesów

Pozostań przy XL gdy:

• Skala > 80 M zł obrotu, dużo customów ERP-owych
• Twój dział księgowości pracował na XL latami
• Wymagasz konkretnych modułów branżowych XL

Co dalej

• Inne ERP-y: Comarch XL, Subiekt GT, SAP
• Architektura integracji: Middleware vs. bezpośrednio
• Platforma sklepu: Shopware 6
• Pełny przegląd integracji: pillar /integracje

Najczęstsze pytania