W tym artykule
wFirma API to interfejs, przez który program sklepu albo własny skrypt wystawia faktury, dodaje kontrahentów i pobiera dokumenty w wFirma bez logowania do panelu. Zapytania wysyłasz pod adres api2.wfirma.pl, a uwierzytelniasz się kluczami API albo przez aplikację z tokenem dostępu.
Z API korzystają głównie twórcy integracji i sklepy z własnym systemem. Jeśli sprzedajesz na Shoperze, PrestaShopie albo Magento, wFirma ma gotowe połączenie i programować nie musisz. W tym przewodniku znajdziesz oba scenariusze, a także to, jak API wFirma wiąże się z KSeF.
Krótko mówiąc
- wFirma API przyjmuje zapytania pod adresem api2.wfirma.pl. Adres to zawsze moduł i akcja, na przykład invoices/add albo contractors/find.
- Do kluczy API potrzebujesz trzech wartości: accessKey i secretKey z panelu oraz appKey, który wFirma wydaje twórcy integracji.
- Dane wysyłasz w XML (domyślnie) albo w JSON. Format wybierasz parametrami inputFormat i outputFormat.
- Limitów liczby zapytań wFirma nie publikuje w liczbach. Zależą od obciążenia serwera, a ciężkie operacje zaleca robić w nocy.
- Faktura pobrana przez API ma numer i status KSeF, a webhook powiadomi Cię o zmianie statusu. Wysyłkę do KSeF ustawiasz w panelu wFirma.
Co to jest wFirma API i do czego służy
API wFirma działa według prostej konwencji. Adres zapytania to zawsze moduł i akcja: https://api2.wfirma.pl/NAZWA_MODUŁU/NAZWA_AKCJI. Akcje mają stałe nazwy: get, find, add, edit i delete. Do tego dochodzą akcje specjalne, na przykład pobranie PDF faktury.
Dane wymieniasz w XML albo w JSON. Domyślny jest XML, a format zmieniasz parametrami w adresie, na przykład ?inputFormat=json&outputFormat=json. Serwer sam przelicza dane między formatami, więc możesz wysyłać JSON i odbierać XML.
Pełny opis każdego modułu, z listą pól i przykładami, publikuje dokumentacja API wFirma. Najczęściej korzystają z niej trzy grupy:
- sklepy z własnym silnikiem, które chcą wystawiać fakturę zaraz po opłaceniu zamówienia,
- twórcy programów do sprzedaży i magazynu, którzy łączą swoje narzędzie z księgowością klienta,
- biura rachunkowe, które automatyzują pobieranie dokumentów od wielu firm.
Moduły API wFirma: co da się zautomatyzować
Dokumentacja opisuje kilkadziesiąt modułów. Dla sprzedaży w internecie liczy się kilka z nich.
| Obszar | Moduły | Co zrobisz |
|---|---|---|
| Sprzedaż | invoices, invoices_correction |
wystawisz fakturę i korektę, pobierzesz PDF, wyślesz fakturę e-mailem do klienta |
| Sprzedaż wysyłkowa | invoice_deliveries |
rozliczysz dostawę, gdy data dostarczenia nie była znana przy wystawieniu |
| Kontrahenci | contractors |
dodasz, wyszukasz i poprawisz dane kupujących |
| Towary i magazyn | goods, warehouses, warehouse_documents |
dodasz towary i dokumenty magazynowe, na przykład PZ i WZ |
| Płatności | payments, payment_cashboxes |
zapiszesz wpłatę do faktury |
| Koszty i dokumenty | expenses, documents |
odczytasz wydatki, dodasz i pobierzesz dokumenty |
| Powiadomienia | webhooks |
dostaniesz sygnał o nowej fakturze, płatności, zmianie stanu towaru i statusu KSeF |
Moduł faktur ma też akcje fiscalize i unfiscalize. Oznaczają one paragon fiskalny jako zafiskalizowany albo cofają to oznaczenie. Sam druk paragonu wFirma obsługuje przez integrację z drukarkami fiskalnymi.
Porada profesjonalisty
zamiast co minutę pytać API o nowe płatności, zarejestruj webhook payments/add. Odciążysz limit zapytań, a wpłata trafi do Twojego systemu od razu.
Jak się uwierzytelnić: klucze API i aplikacja z tokenem
wFirma daje dwie główne drogi dostępu. Wybór zależy od tego, czy integrujesz jedną firmę, czy budujesz aplikację dla wielu klientów.
Klucze API: accessKey, secretKey i appKey
Klucze tworzysz w panelu wFirma w zakładce Ustawienia, Bezpieczeństwo, Aplikacje, Klucze API. Dostajesz tam dwa klucze: accessKey i secretKey. Trzeci, appKey, wydaje wFirma twórcy integracji. Zamawiasz go formularzem kontaktowym, podając nazwę aplikacji, telefon, e-mail i adres strony.
Jeden appKey obsłuży wiele kont użytkowników wFirma. Każde zapytanie niesie wszystkie trzy klucze w nagłówkach accessKey, secretKey i appKey. Inne parametry autoryzacji nie są potrzebne.
Dwie rzeczy zaskakują najczęściej. secretKey wyświetla się tylko raz, podczas tworzenia kluczy. Każda zmiana klucza aplikacji w panelu zmienia też accessKey i secretKey, więc integracja przestaje działać do czasu wpisania nowych wartości.
Aplikacja z tokenem dostępu (wersja 2.0)
Druga droga to aplikacja, którą użytkownik autoryzuje, logując się do wFirma. Tworzysz ją w zakładce Ustawienia, Bezpieczeństwo, Aplikacje, w sekcji aplikacji w wersji 2.0. Podajesz nazwę, zakres uprawnień, adres zwrotny i adres IP serwera.
Aplikację utworzysz tylko na zweryfikowanej firmie, a potem sprawdzają ją pracownicy wFirma. Po weryfikacji dostajesz client_id i client_secret. Użytkownik loguje się, Ty wymieniasz otrzymany kod na token pod adresem https://api2.wfirma.pl/oauth2/token?oauth_version=2, a token wysyłasz w nagłówku Authorization jako Bearer. Do każdego zapytania dodajesz wtedy parametr ?oauth_version=2.
Zakresy dzielą każdy moduł na odczyt i zapis, na przykład invoices-read i invoices-write. Zapytanie spoza przyznanego zakresu kończy się błędem DENIED SCOPE REQUESTED. Dokumentacja opisuje też starszą wersję 1.0a tego standardu, z kluczami wydawanymi przez wFirma na prośbę wysłaną e-mailem.
| Sposób | Dla kogo | Co musisz zrobić |
|---|---|---|
| Klucze API | jedna firma albo integrator obsługujący klientów jednym appKey | utworzyć klucze w panelu i zamówić appKey |
| Aplikacja z tokenem (2.0) | aplikacja, do której loguje się wielu użytkowników wFirma | zweryfikować firmę, utworzyć aplikację i przejść weryfikację wFirma |
Porada profesjonalisty
trzymaj secretKey w menedżerze sekretów, a nie w kodzie ani w pliku konfiguracyjnym w repozytorium. Skoro wFirma pokazuje go tylko raz, zgubiony klucz oznacza nową parę kluczy i przestawienie integracji.
Pierwsze zapytanie: format danych i parametr company_id
Odpowiedź API ma najwyżej dwie gałęzie najwyższego poziomu. Pierwsza nosi nazwę modułu, na przykład invoices, i zawiera rekordy. Druga to status z kodem wyniku, na przykład OK.
Przykład dodania faktury wygląda w dokumentacji tak. To fragment skrócony do najważniejszych pól:
<api>
<invoices>
<invoice>
<contractor>
<name>Testowy kontrahent</name>
<zip>10-100</zip>
<city>Wrocław</city>
</contractor>
<type>normal</type>
<invoicecontents>
<invoicecontent>
<name>123123</name>
<count>1.0000</count>
<price>9699.00</price>
<unit>szt.</unit>
</invoicecontent>
</invoicecontents>
</invoice>
</invoices>
</api>
Jeśli Twoje konto ma kilka firm, dodawaj do każdego zapytania parametr company_id. Bez niego dokument może trafić do innej firmy, niż zakładasz. Listę firm pobierzesz akcją user_companies/find, a przy braku parametru API zwraca błąd COMPANY ID REQUIRED.
Wyszukiwanie przez find przyjmuje numer strony (od 1) i limit wyników na stronę. Możesz też ograniczyć odpowiedź do wybranych pól, na przykład numeru i daty faktury. Według dokumentacji może to wyraźnie przyspieszyć zapytania.
Limity, błędy i dobre praktyki
wFirma nie publikuje liczbowych limitów zapytań. Przekroczenie sygnalizują dwa błędy: TOTAL REQUESTS LIMIT EXCEEDED (za dużo zapytań) i TOTAL EXECUTION TIME LIMIT EXCEEDED (za długi łączny czas wykonania). Dokumentacja tłumaczy, że limity zależą od bieżącego obciążenia serwera. Zaleca wykonywanie cięższych zapytań w nocy i unikanie serii zapytań w krótkich odstępach.
Inne komunikaty, które warto obsłużyć w kodzie:
AUTH FAILED LIMIT WAIT 5 MINUTES: za dużo nieudanych logowań, kolejna próba dopiero po pięciu minutach,OUT OF SERVICE: API chwilowo wyłączone, na przykład podczas aktualizacji,SNAPSHOT LOCK: trwa odtwarzanie danych firmy z kopii i wszystkie operacje są zablokowane,ERROR: błędy walidacji, które API dokleja do przesłanego rekordu, przy konkretnych polach.
Najważniejsza praktyka dotyczy zapisów. Gdy dodanie faktury skończy się błędem limitu albo przerwanym połączeniem, nie ponawiaj go w ciemno. Najpierw sprawdź przez find, czy faktura nie powstała. Inaczej klient dostanie dwie faktury za jedno zamówienie.
wFirma i KSeF: co robi panel, a co pokazuje API
Wysyłkę faktur do KSeF w wFirma ustawiasz w panelu, w zakładce Przychody, KSeF. Według centrum pomocy wFirma administrator wybiera zakres integracji: import faktur zakupu, wysyłkę faktur dla firm, wysyłkę faktur dla konsumentów i pobieranie sprzedaży. Faktura dla firmy może trafić do KSeF od razu po zapisaniu, a przycisk „Zapisz i wyślij do KSeF” robi obie rzeczy naraz.
Do połączenia z KSeF wFirma przyjmuje trzy rodzaje autoryzacji:
- certyfikat wygenerowany w wFirma,
- własny certyfikat z Ministerstwa Finansów,
- token, którego według wFirma można używać tylko do końca 2026 roku.
Autoryzacja działa na użytkownika, więc każdy pracownik autoryzuje się na swoim koncie. Integracja z KSeF jest w pakietach, bez dodatkowej opłaty.
API pokazuje wynik tej wysyłki. Faktura ma pola ksef_reference_number (numer nadany przez KSeF), ksef_status i ksef_registration_date, wszystkie tylko do odczytu. Osobnej akcji wysyłki do KSeF dokumentacja API nie opisuje. Zmianę statusu zgłosi Ci webhook invoice_ksefs/change_state.
Porada profesjonalisty
przed uruchomieniem integracji dodaj przez API jedną fakturę testową dla firmy i sprawdź, czy automatyczna wysyłka z panelu ją obejmuje. Webhook statusu KSeF potwierdzi wynik bez ręcznego zaglądania do wFirma.
Terminy obowiązku KSeF centrum pomocy wFirma podaje dla typowej firmy tak: odbiór faktur zakupowych od 1 lutego 2026 roku i wysyłka faktur sprzedaży od 1 kwietnia 2026 roku. Największe firmy, ze sprzedażą powyżej 200 mln zł w 2024 roku, wystawiają faktury w KSeF już od 1 lutego 2026 roku. Najmniejsze, ze sprzedażą na fakturach do 10 tys. zł miesięcznie, mają czas do 1 stycznia 2027 roku. Więcej o obowiązkach sklepów piszemy w artykule faktury KSeF w e-commerce.
Jak połączyć sklep z wFirma: gotowa integracja czy własne API
Zanim zaczniesz programować, sprawdź listę gotowych połączeń. Serwis wFirma wymienia integracje ze sklepami, między innymi Shoper, Clickshop, Magento, PrestaShop, CS-Cart, Gekosale i CStore. Po zarejestrowaniu zamówienia w sklepie dokument sprzedaży może powstać w wFirma automatycznie.
Sprzedaż z Allegro wFirma opisuje przez integrację z programem Apilo. Integrację z wFirma deklaruje też Base.com. WooCommerce na liście wFirma nie ma, więc tu zostaje program pośredniczący albo własne API.
Jeśli budujesz integrację sam, przejdź te kroki:
- Sprawdź gotowe integracje. Własny kod ma sens dopiero wtedy, gdy żadna z nich nie pasuje.
- Zdobądź klucze. Utwórz accessKey i secretKey w panelu i zamów appKey w wFirma.
- Ustal company_id. Pobierz listę firm i zapisz identyfikator tej, w której wystawiasz faktury.
- Zmapuj dane zamówienia. Pozycje, stawki VAT, koszt dostawy, sposób płatności i dane do faktury.
- Przetestuj na kilku zamówieniach. Sprawdź sumy, numerację, PDF i status KSeF.
- Dodaj webhooki i monitoring. Reaguj na płatności i statusy KSeF, a błędy zapisuj w dzienniku.
Własna integracja ma sens przy nietypowym sklepie, dużej liczbie dokumentów albo specyficznym przepływie, na przykład przy fakturach zbiorczych. Pamiętaj o koszcie utrzymania. API się rozwija, a dokumentacja wprost zastrzega, że w odpowiedziach mogą pojawić się nowe gałęzie, które Twój kod musi bezpiecznie pominąć.
Faktury prosto z programu do sprzedaży
Jeśli sprzedajesz na kilku kanałach naraz, wygodniej bywa wystawiać faktury tam, gdzie i tak obsługujesz zamówienia. Wtedy nie budujesz osobnego połączenia z systemem fakturowym dla każdego sklepu.
W Berlinettcie faktura powstaje z danych zamówienia z Allegro, Erli albo Twojego sklepu, pojedynczo albo hurtem. Program sam wybiera fakturę albo paragon, zależnie od tego, czy kupujący prosił o fakturę. Gotową fakturę wysyłasz do KSeF bez wychodzenia z programu, a przy dokumencie zostaje numer KSeF, status i potwierdzenie odbioru.
Z wFirma Berlinetta się nie łączy. Jeśli wolisz zewnętrzny system fakturowy, masz dwie gotowe drogi:
- inFakt: faktury i korekty do zamówień powstają w Twoim inFakcie, z listy nawet 100 naraz, a numer, PDF i płatność wracają do Berlinetty. Jak działa samo API inFakt, opisujemy w artykule inFakt API.
- Subiekt nexo PRO: faktury i paragony wystawia Subiekt na Twoim komputerze, a paragon fiskalizuje na Twojej drukarce fiskalnej.
Biuru rachunkowemu pobierzesz albo wyślesz e-mailem plik JPK_V7M. Wszystko to jest w każdym pakiecie, od 89 zł netto miesięcznie, a pierwsze 30 dni testujesz bezpłatnie.
Z praktyki: błędy, które psują integrację z wFirma
Najdroższy błąd to podwójna faktura. Skrypt dostaje błąd limitu, ponawia invoices/add, a pierwsza próba jednak się udała. Każdy zapis powinien mieć w Twoim systemie znacznik zamówienia, po którym sprawdzisz, czy faktura już istnieje.
Drugi błąd to zmiana klucza w panelu bez aktualizacji integracji. Ktoś „porządkuje” aplikacje w ustawieniach, a sklep od tej chwili nie wystawia faktur. Ustal, kto może zmieniać klucze, i ustaw alert na błąd AUTH.
Trzeci błąd dotyczy sprzedaży wysyłkowej. Przy wystawieniu faktury nie znasz daty dostarczenia paczki. API ma na to pole disposaldate_empty i osobne rozliczenie dostawy w module invoice_deliveries. Kto o tym nie wie, wpisuje datę sprzedaży na oko.
Czwarty błąd to parser JSON, który oczekuje listy. W JSON wFirma rekordy są numerowane kluczami „0”, „1”, nawet gdy jest tylko jeden. Kod napisany pod tablicę wywraca się przy pierwszej odpowiedzi.
Integracja z systemem fakturowym działa latami bez dotykania tylko wtedy, gdy od początku zakładasz błędy po stronie sieci, limitów i ludzi. Zapis, który da się bezpiecznie powtórzyć, oszczędza więcej czasu niż najszybszy kod.
