Fakturownia API z PrestaShop i WooCommerce - od połączenia do faktury

Co uruchamiasz i co sprawdzasz

Ta instrukcja opisuje gotowe połączenie w NavyFlame: zamówienie z WooCommerce lub PrestaShop trafia do panelu, a reguła wystawia do niego fakturę albo paragon w Fakturowni. Na jednym zamówieniu sprawdzasz trzy osobne wyniki:

1. Zamówienie w NavyFlame z kompletem danych: źródło, identyfikator, kwoty, nabywca i NIP.
2. Dokument w Fakturowni zgodny z zamówieniem i z nim powiązany.
3. Dalsze etapy w Fakturowni, czyli wysyłka do KSeF i ewentualny e-mail do kupującego. Utworzenie dokumentu ich nie potwierdza.

Nazwy pól i przycisków oraz sposób przenoszenia danych na fakturę opisujemy według produkcyjnej wersji NavyFlame z 1 listopada 2026 r. Opisane opcje nie są w panelu oznaczone jako testowe, a automatyczne faktury i integracje bez limitu kont są według aktualnej oferty w każdym planie. Zakres obu połączeń opisują strony PrestaShop z Fakturownią i WooCommerce z Fakturownią. Jeśli dopiero decydujesz, czy zostać przy wtyczce do faktur w WooCommerce, zacznij od porównania wtyczki i integratora. Rodzaj dokumentu, moment jego wystawienia i stawki VAT ustal z osobą prowadzącą księgowość.

1. Przygotuj dostęp w trzech systemach

W WooCommerce klucz ma w polu Uprawnienia jeden z trzech poziomów: Odczyt, Zapis albo Zapis/odczyt. Do pobierania zamówień wystarczy Odczyt. Zapis/odczyt jest potrzebny, jeśli NavyFlame ma odsyłać zmiany do sklepu, na przykład status zamówienia oznaczonego w panelu jako zrealizowane.

W PrestaShop webservice jest domyślnie wyłączony, a uprawnienia nadajesz osobno dla każdego zasobu. W PrestaShop 9 nie myl tej pozycji z Admin API. Daj kluczowi odczyt zamówień (orders) i zasobów, z których NavyFlame uzupełnia zamówienie: statusów (order_states), klientów (customers), adresów (addresses), krajów (countries) i przewoźników (carriers). Brak odczytu adresów lub klientów nie zatrzymuje pobierania. Bez odczytu adresów zamówienie trafi do panelu bez adresu i NIP-u, więc firmy nie da się rozpoznać po NIP-ie. Bez odczytu klientów zabraknie w nim e-maila kupującego. Dodatkowe opcje połączenia mają własne wymagania, opisane przy każdym polu w panelu.

Token Fakturowni i klucze sklepu wpisuj tylko w formularzu połączenia. Nie umieszczaj ich w zgłoszeniach, na zrzutach ekranu ani w adresach stron.

Jeśli dziś faktury wystawia wtyczka w sklepie albo integracja po stronie Fakturowni, ustal, od którego zamówienia dokumenty wystawia NavyFlame. Dwa automaty działające na tych samych zamówieniach mogą wystawić dwie faktury do jednej sprzedaży.

2. Połącz konta i sprawdź pierwsze pobrane zamówienie

W NavyFlame otwórz Integracje i dodaj sklep oraz Fakturownię. Formularz Fakturowni ma pola Token API, Adres konta Fakturownia i opcjonalne ID działu (Department ID), które uzupełnia dane sprzedawcy na fakturze. Wystawcę i numerację po stronie Fakturowni opisuje przewodnik po ustawieniach Fakturowni.

Przy WooCommerce zdecyduj o polu Pobranie nieopłacone do doręczenia, domyślnie wyłączonym. WooCommerce według swojej dokumentacji nadaje zamówieniu za pobraniem status „W trakcie realizacji” (processing), zanim pieniądze zostaną pobrane, a NavyFlame traktuje ten status jako opłacenie. Bez tej opcji, przy wyzwalaczu po opłaceniu, faktura do zamówienia za pobraniem powstanie zaraz po jego pobraniu do NavyFlame i w Fakturowni będzie oznaczona jako opłacona. Po włączeniu opcji takie zamówienie czeka jako nieopłacone, aż kurier doręczy paczkę albo potwierdzisz płatność w panelu.

Przy PrestaShop opcja Odczyt kwoty i daty wpłaty do faktury, także domyślnie wyłączona, przenosi na fakturę datę wpłaty. Wymaga odczytu zasobów orders, order_payments i currencies. Opis pola w panelu wyjaśnia, kiedy wpłata zostaje uznana za nieznaną, na przykład przy wspólnej referencji kilku zamówień. Bez tej opcji faktura do opłaconego zamówienia jest oznaczona jako opłacona, ale bez daty wpłaty.

NavyFlame pobiera zamówienia ze sklepu cyklicznie przez API, więc nowe zamówienie pojawia się w panelu po najbliższym pobraniu. Otwórz Zamówienia i porównaj jedno zamówienie z widokiem w sklepie: identyfikator, kwotę, dostawę, nabywcę i NIP. Jeśli zamówienia brakuje, sprawdź adres sklepu, klucz i jego uprawnienia. Do reguł fakturowania przejdź, gdy zamówienia pobierają się poprawnie.

3. Dodaj przepływ danych i ustaw reguły

Otwórz Automatyzacje, zakładkę Przepływy danych, i kliknij Dodaj. Jako Źródło (Marketplace) wybierz sklep, a jako Cel (Księgowość) Fakturownię. Bez przepływu NavyFlame nie wystawia dokumentów automatycznie, a fakturę utworzysz tylko przyciskiem Wystaw fakturę na zamówieniu.

Następnie w sekcji Fakturowanie → Reguły wybierz ten przepływ, na przykład WooCommerce → Fakturownia. Najważniejsze pola i ich ustawienia domyślne:

Wyzwalacz „Zrealizowane” reaguje na zmianę statusu zamówienia w NavyFlame, na przykład w panelu. Jeśli zamówienia oznaczasz jako zrealizowane tylko w sklepie, sprawdź ten wariant na zamówieniu testowym, zanim go wybierzesz.

Paragon dla sprzedaży konsumenckiej wybierasz w polu Domyślny dokument B2C (krajowy, PL). Taki wybór uzgodnij z księgowością. Paragony z drukarki fiskalnej obsługuje w NavyFlame osobne połączenie Paragony.pl.

Skąd NavyFlame bierze NIP

Przy ustawieniu NIP (Polska) numer musi mieć 10 cyfr i poprawną cyfrę kontrolną. Spacje, kreski i prefiks PL nie przeszkadzają. Numer, który nie przejdzie tej kontroli, nie oznacza zamówienia jako firmowego. Ustawienie VAT Number (UE) wymaga prefiksu kraju, więc polski NIP wpisany bez PL nie zostanie przy nim rozpoznany.

Jeśli wtyczka WooCommerce zapisuje NIP pod inną nazwą pola, NavyFlame go nie zobaczy. W trybie Zawsze firma dostanie wtedy dokument jak konsument, a w trybach Na żądanie lub B2B oraz Tylko B2B nie dostanie żadnego. Jeśli automatyczna wysyłka do KSeF działa w Fakturowni w trybie „Tylko dokumenty wystawiane dla firm z Polski” albo „Wszystkie dokumenty wystawiane dla firm”, faktura wystawiona jak dla konsumenta nie trafi tam automatycznie, bo w tych trybach Fakturownia wysyła tylko faktury oznaczone jako dla firmy. Zanim włączysz automat, złóż zamówienie testowe z NIP-em i sprawdź, czy NIP widać w danych nabywcy w NavyFlame.

Tryb Na żądanie lub B2B wymaga, żeby prośba o fakturę dotarła do NavyFlame. Z WooCommerce połączenie odczytuje tylko NIP, a zaznaczenia w rodzaju „chcę fakturę” dodanego przez wtyczkę koszyka nie odczytuje. Jeśli w WooCommerce kupujący bez NIP-u proszą o fakturę imienną, wybierz tryb Zawsze. W PrestaShop sprawdź taki przypadek na zamówieniu testowym, zanim wybierzesz tryb Na żądanie lub B2B.

4. Jak dane zamówienia trafiają na fakturę

Jeśli NavyFlame nie ustali stawki VAT pozycji, na przykład gdy WooCommerce nie nalicza podatków, nie wystawi dokumentu ze stawką 0% przyjętą bez podstawy. W sekcji Fakturowanie zamówienia pojawi się status „Błąd”, a komunikat wskaże pozycję, dla której trzeba ustalić stawkę. Skąd reguła bierze stawki, ustawisz w polu Źródło stawki VAT w karcie VAT i OSS. Sposób uzupełnienia uzgodnij z księgowością.

Jeśli doliczasz w WooCommerce opłaty, na przykład za wybraną płatność, pokaż księgowości fakturę z próby, zanim włączysz automat dla całej sprzedaży.

5. Sprawdź wynik na zamówieniach testowych

Przykład demonstracyjny z fikcyjnymi kwotami: dwa produkty za 120 zł i 80 zł brutto, kupon na 20 zł i dostawa za 15 zł, czyli 195 zł do zapłaty. Na fakturze powinny się znaleźć dwie pozycje towarowe po rabacie, łącznie 180 zł (przy rabacie rozłożonym proporcjonalnie 108 zł i 72 zł), osobna pozycja dostawy za 15 zł i suma 195 zł, bez osobnej pozycji rabatu.

Potem przejdź przez przypadki, które naprawdę występują w Twojej sprzedaży:

Wynik sprawdzasz w karcie zamówienia w NavyFlame, w sekcji Fakturowanie, i w samej Fakturowni. W NavyFlame zwróć uwagę na status dokumentu: rodzaj dokumentu albo „Wystawiony”, „W toku”, „Błąd” lub „Nie wystawiono”. Ten status dotyczy utworzenia dokumentu. Numer KSeF i ewentualny e-mail do kupującego sprawdzasz w Fakturowni.

Anulowanie zamówienia w sklepie nie tworzy korekty wystawionej faktury. Korekty po zwrotach to osobny tryb w karcie Refundy i korekty, domyślnie wyłączony.

6. Gdy wynik jest inny niż oczekiwany

„Nie wystawiono”. Reguła celowo pominęła zamówienie, a panel pokazuje powód. Powodem może być tryb fakturowania albo brak NIP-u rozpoznanego przez Wykrywanie B2B. Zmień regułę, jeśli takie zamówienie ma dostawać dokument.

„Błąd”. Przeczytaj komunikat, usuń przyczynę, na przykład brak stawki VAT albo nieaktualny token Fakturowni, i dopiero wtedy kliknij Ponów. Ponowienie bez zmiany przyczyny skończy się tym samym błędem.

Niepewny wynik po przerwanym połączeniu. Zanim ponowisz, odszukaj zamówienie w Fakturowni. NavyFlame przekazuje identyfikator zamówienia w polu oid z zakazem duplikatu, a Fakturownia według swojej dokumentacji nie pozwala wtedy utworzyć drugiej faktury z tym samym identyfikatorem. Ta ochrona nie obejmuje dokumentów wystawionych ręcznie, wtyczką ani innym integratorem. Jeśli faktura istnieje w Fakturowni, a NavyFlame pokazuje błąd, nie wystawiaj jej ponownie ręcznie, tylko zgłoś sprawę przez Wsparcie z identyfikatorem zamówienia i godziną.

Dwa sklepy, jedno konto Fakturowni. Identyfikatory zamówień z dwóch sklepów mogą się powtarzać. Fakturownia nie utworzy wtedy drugiej faktury z tym samym oid, więc zamówienie z drugiego sklepu nie dostanie własnego dokumentu. Zanim podłączysz drugi sklep do tego samego konta, porównaj zakresy identyfikatorów zamówień w obu sklepach, a przy pierwszych zamówieniach drugiego sklepu sprawdź w Fakturowni, czy każde ma swoją fakturę.

Do zgłoszenia przygotuj identyfikator zamówienia, czas i treść komunikatu, bez tokenów i kluczy.

Własna integracja przez API Fakturowni

Dokumentacja API Fakturowni opisuje token konta, tworzenie faktur, pole oid z opcją oid_unique oraz osobną wysyłkę dokumentu e-mailem. Samo żądanie tworzące fakturę nie stanowi jednak kompletnej integracji. Własny program musi też obsłużyć powtarzające się zdarzenia ze sklepu, odpowiedź, która nie dotarła, limity API, powiązanie dokumentu z zamówieniem i wyjątki z tabel powyżej, w tym NIP, rabat, dostawę i płatność za pobraniem.

Próba na własnym sklepie

W scenariuszu sklepu i fakturowania przejdziesz przez zamówienie, reguły fakturowania i listę dokumentów na danych przykładowych. Demo nie łączy się z Twoim sklepem ani z Fakturownią i nie wystawia dokumentów, więc nie potwierdza zgodności sklepu, wtyczek ani wyniku faktury.

W próbie zacznij od jednego sklepu i jednego konta Fakturowni. Zapisz identyfikatory zamówień testowych i numery dokumentów. Zakres rozszerzaj dopiero wtedy, gdy wszystkie przypadki z tabeli w punkcie 5 dają oczekiwany wynik, a osoba odpowiedzialna za wyjątki wie, gdzie je znaleźć.

Źródła

Sprawdzone 1 listopada 2026 r.:

• Fakturownia API - miejsce tokenu API, pole oid jako numer zamówienia i oid_unique, przy którym system nie pozwoli stworzyć dwóch faktur o tym samym oid, osobna wysyłka faktury e-mailem.
• Fakturownia: przewodnik integracji KSeF - tryby automatycznej wysyłki do KSeF ustawiane w Fakturowni i znaczenie oznaczenia nabywcy jako firmy: w trybach „Tylko dokumenty wystawiane dla firm z Polski” i „Wszystkie dokumenty wystawiane dla firm” wysyłane są tylko faktury z buyer_company=true.
• WooCommerce REST API - tworzenie kluczy i poziomy uprawnień Read, Write oraz Read/Write.
• WooCommerce: Cash on Delivery - zamówienia za pobraniem mają status Processing, dopóki płatność nie zostanie pobrana.
• WooCommerce: Direct Bank Transfer (BACS) - zamówienie opłacane przelewem tradycyjnym ma status On hold, bo przed jego realizacją sprzedawca musi sprawdzić wpłatę na koncie bankowym.
• Polskie tłumaczenie WooCommerce - nazwy statusów „W trakcie realizacji” i „Wstrzymane (oczekujące na płatność)” oraz pól klucza API: „Klucz konsumenta”, „Tajny konsumenta”, „Uprawnienia”, „Odczyt”, „Zapis” i „Zapis/odczyt”.
• PrestaShop: Creating access to the Webservice - webservice domyślnie wyłączony, klucz z uprawnieniami nadawanymi dla każdego zasobu.
• PrestaShop: polskie tłumaczenie menu panelu i ustawień API wersji 9 - menu Konfiguruj → Zaawansowane, pozycja Webservice nazywa się „API”, opcje „Włącz API PrestaShop” i „Dodaj nowy klucz API”, osobne Admin API. Te same nazwy menu i opcji mają pliki wersji 8.