Fakturownia API - integracja sklepu krok po kroku

Po co integrować sklep z Fakturownią przez API

Fakturownia to jeden z najpopularniejszych w Polsce systemów do wystawiania faktur, a jego siłą jest dobrze zaprojektowane API REST. Dla sklepu internetowego oznacza to jedno: każde zamówienie może zamienić się w poprawną fakturę bez przepisywania danych ręcznie.

Ręczne fakturowanie działa, dopóki masz kilkanaście zamówień dziennie. Przy większej skali to wąskie gardło - kosztuje czas, generuje literówki w NIP-ie i opóźnia wysyłkę dokumentów. Integracja przez API przenosi dane wprost z zamówienia na fakturę, więc dokument powstaje w sekundę po zakupie.

W tym przewodniku pokazujemy, jak działa ta integracja od strony praktycznej: co znajduje się w API Fakturowni, jak przygotować klucz, jak mapować dane oraz dlaczego obsługa błędów jest równie ważna co samo wystawienie faktury.

Co udostępnia API Fakturowni

API Fakturowni jest interfejsem REST - komunikacja odbywa się przez standardowe żądania HTTP, a dane przesyłane są w formacie JSON. Z punktu widzenia sklepu najważniejsze są operacje na dokumentach.

• Tworzenie faktur VAT na podstawie danych zamówienia.
• Wystawianie proform, faktur zaliczkowych i rachunków.
• Generowanie faktur korygujących przy zwrotach i reklamacjach.
• Pobieranie wystawionych dokumentów, na przykład w celu wysyłki PDF do klienta.
• Zarządzanie danymi kontrahentów i pozycjami katalogowymi.

Każde żądanie wymaga uwierzytelnienia kluczem API powiązanym z Twoim kontem. Klucz pełni rolę poświadczenia - to on decyduje, na którym koncie i w której serii numeracji powstanie dokument.

Dla sprzedawcy wielokanałowego liczy się też to, że API pozwala prowadzić osobne serie numeracji. Możesz na przykład inaczej numerować faktury krajowe, a inaczej zagraniczne albo trzymać oddzielną serię dla każdego kanału sprzedaży. To porządkuje dokumentację i ułatwia późniejsze raportowanie.

Krok 1: Wygeneruj klucz API w Fakturowni

Zanim cokolwiek połączysz, potrzebujesz klucza API. Znajdziesz go w panelu Fakturowni, w ustawieniach konta, w sekcji poświęconej API lub integracjom. Wygenerowany klucz skopiuj i przechowaj w bezpiecznym miejscu.

Klucz API działa jak hasło do wystawiania dokumentów na Twoim koncie. Z tego powodu nigdy nie umieszczaj go w kodzie po stronie przeglądarki ani w publicznym repozytorium. Powinien trafić wyłącznie do konfiguracji backendu lub do panelu integratora, który trzyma sekrety po bezpiecznej stronie.

Jeśli klucz zostanie skompromitowany, możesz go w każdej chwili unieważnić i wygenerować nowy. Warto też okresowo go rotować, zwłaszcza gdy dostęp do konta miało wiele osób.

Krok 2: Zmapuj dane zamówienia na pola faktury

Najważniejszy etap integracji to mapowanie - czyli ustalenie, które pole zamówienia trafia do którego pola faktury. To tu rozstrzyga się, czy dokument będzie poprawny.

Typowe mapowanie obejmuje:

• Dane nabywcy: imię i nazwisko lub nazwę firmy, adres oraz NIP przy sprzedaży B2B.
• Pozycje zamówienia: nazwę produktu, ilość, cenę jednostkową i stawkę VAT.
• Datę sprzedaży i datę wystawienia dokumentu.
• Formę i termin płatności, jeśli wynika z zamówienia.

Najwięcej problemów sprawia stawka VAT i NIP. Gdy dane są niespójne lub niekompletne, faktura wyjdzie błędna, a poprawianie jej po fakcie kosztuje więcej niż dopilnowanie danych na wejściu. Dlatego dobra integracja waliduje dane zamówienia, zanim wyśle je do API Fakturowni.

Jeśli zastanawiasz się nad budową takiej logiki samodzielnie, zajrzyj do porównania własna integracja API czy gotowy integrator - mapowanie i walidacja to właśnie ta część, która okazuje się najbardziej pracochłonna.

Krok 3: Zadbaj o obsługę błędów i ponawianie

Samo wysłanie żądania do API to dopiero połowa sukcesu. Żadne API nie odpowiada poprawnie w stu procentach przypadków - zdarzają się chwilowe niedostępności, limity zapytań czy przejściowe błędy sieci. Jeśli integracja nie poradzi sobie z takim przypadkiem, faktura po prostu się nie wystawi, a Ty dowiesz się o tym dopiero od klienta.

Solidna integracja powinna:

• Ponawiać nieudane próby (retry) z odstępem, zamiast poddawać się po pierwszym błędzie.
• Rozróżniać błędy przejściowe od trwałych (na przykład brak NIP-u to błąd danych, a nie sieci).
• Kierować nieudane zamówienia do kolejki błędów z czytelnym opisem przyczyny.
• Pozwalać na ponowne przetworzenie zamówienia po naprawieniu problemu.

Ten element jest często niedoceniany przy samodzielnym pisaniu integracji, a w praktyce odpowiada za większość późniejszych kłopotów. Faktura, która cicho nie powstała, to brakujący dokument w księgowości i potencjalny problem przy rozliczeniu.

Własna integracja API kontra gotowy connector

API Fakturowni jest na tyle czytelne, że napisanie własnej integracji jest możliwe. Pytanie brzmi raczej: czy to się opłaca. Samodzielny kod oznacza, że bierzesz na siebie utrzymanie, aktualizacje, obsługę błędów, ponawianie prób oraz monitoring - i to dla każdego kanału sprzedaży osobno.

Gotowy integrator zdejmuje ten ciężar. NavyFlame łączy się z Fakturownią po stronie serwera, przechowuje klucz API bezpiecznie i obsługuje całą logikę mapowania, walidacji oraz ponawiania. Ty podajesz klucz, ustawiasz reguły i monitorujesz status, zamiast utrzymywać własny kod.

Schemat działania jest prosty:

1. Klient składa zamówienie na marketplace lub w sklepie.
2. NavyFlame pobiera zamówienie wraz z danymi nabywcy, w tym NIP do faktury B2B.
3. Reguła pipeline decyduje, że faktura ma powstać w Fakturowni.
4. Dane zamówienia są walidowane i mapowane na pola dokumentu.
5. API Fakturowni wystawia fakturę z poprawną stawką VAT i numeracją.
6. Status widzisz w module fakturowania, a błędy możesz ponowić z kolejki jednym kliknięciem.

Dzięki temu jeden przepływ obsługuje wiele źródeł zamówień. Zamówienia z Allegro, WooCommerce czy innych kanałów trafiają do tego samego procesu i kończą się fakturą w Fakturowni - bez logowania się osobno do każdej platformy.

Najczęstsze problemy przy integracji

Kilka rzeczy powtarza się niezależnie od tego, czy integrujesz samodzielnie, czy przez gotowy connector.

• Wygasły lub błędny klucz API - żądania zwracają błąd uwierzytelnienia. Sprawdź klucz i wygeneruj nowy w razie potrzeby.
• Niepełne dane nabywcy - brak NIP-u przy fakturze B2B albo niekompletny adres blokuje wystawienie poprawnego dokumentu.
• Niespójna stawka VAT - jeśli produkt ma przypisaną złą stawkę, faktura będzie błędna. Warto pilnować stawek już na poziomie katalogu.
• Przekroczony limit zapytań API - przy bardzo dużych wolumenach żądania mogą być chwilowo ograniczane. Tu ratuje ponawianie prób z rozsądnym odstępem.

Większości tych problemów da się uniknąć dobrą walidacją danych na wejściu. Reszta to kwestia mechanizmu ponawiania i czytelnej kolejki błędów, żeby żadne zamówienie nie zostało bez faktury.

Jeśli chcesz spojrzeć szerzej na temat samej automatyzacji wystawiania dokumentów, pomocny będzie przewodnik automatyzacja faktur w e-commerce. Pokazuje, jak ułożyć cały proces od zamówienia do gotowej faktury, niezależnie od wybranego systemu fakturowego.

Powyższy materiał ma charakter informacyjny i nie stanowi porady podatkowej ani prawnej. Zasady wystawiania faktur i rozliczania VAT zależą od Twojej sytuacji - w razie wątpliwości skonsultuj się z księgowym lub doradcą podatkowym.

Najczesciej zadawane pytania