API - INTERFEJS DLA PROGRAMISTÓW

W przypadku korzystania z zewnętrznych integracji opartych o API systemu wFirma.pl, przy jednoczesnym włączeniu automatycznej wysyłki faktur do Krajowego Systemu e-Faktur (KSeF), kluczowa jest weryfikacja uprawnień użytkownika dokonującego integracji. Brak odpowiedniej konfiguracji po stronie użytkownika API może skutkować błędami uniemożliwiającymi skuteczne wystawienie dokumentu.

Faktury wystawiane za pośrednictwem API są domyślnie w systemie przypisywane do konkretnego użytkownika – tego, którego dane (klucz API) posłużyły do skonfigurowania integracji.

Oznacza to, że proces wysyłki do KSeF jest realizowany w imieniu tego konkretnego użytkownika. Aby proces przebiegł poprawnie, użytkownik API musi posiadać:

• aktywny dostęp do modułu KSeF w systemie wFirma,
• wygenerowany i zweryfikowany certyfikat / token służący do autoryzacji w systemie ministerialnym.

Najczęstszy problem – brak certyfikatów użytkownika API

Należy pamiętać, że uprawnienia do KSeF nie są dziedziczone automatycznie od administratora głównego.

Jeżeli administrator konta włączył globalną integrację z KSeF, ale użytkownik realizujący integrację przez API nie wgrał własnych certyfikatów, system zablokuje możliwość wystawienia dokumentu.

W takiej sytuacji:

• Faktura nie zostanie utworzona ani wysłana do KSeF.
• API zwróci błąd autoryzacji.

Przykład.
Firma "ABC" korzysta z zewnętrznego programu do sprzedaży e-commerce, który jest zintegrowany z systemem wFirma.pl za pomocą klucza API. Klucz ten został wygenerowany na koncie pracownika – Jana Kowalskiego.

Główny administrator firmy włączył integrację z KSeF na swoim koncie, ale Jan Kowalski nie dokonał autoryzacji w KSeF z systemu wFirma. Gdy program e-commerce próbuje wystawić fakturę, system wFirma zablokuje tę operację i zwróci błąd. Dzieje się tak, ponieważ system próbuje wysłać fakturę do KSeF w imieniu Jana, który nie posiada autoryzacji w KSeF.

Jan Kowalski musi zalogować się na swoje konto w wFirma.pl, przejść do zakładki Przychody » KSeF i Integracje i dodać swój certyfikat w KSeF. Po tej czynności faktury przekazywane za pośrednictwem API będą wystawiane i wysyłane poprawnie do KSeF.

1. Zaloguj się na konto użytkownika, którego klucz API jest wykorzystywany w integracji.

2. Przejdź do zakładki PRZYCHODY » KSEF I INTEGRACJE.

3. W sekcji konfiguracji upewnij się, że status integracji jest aktywny.

4. Jeśli występuje brak autoryzacji, kliknij przycisk Włącz integrację i postępuj zgodnie z instrukcjami, aby wgrać wymagane certyfikaty lub token.

Prawidłowa konfiguracja uprawnień oraz autoryzacji KSeF jest niezbędna dla skutecznej wysyłki faktur z wFirma do KSeF.

Wybór użytkownika, którego autoryzacja będzie wykorzystywana do wysyłki faktur

Aby uprościć proces integracji, w systemie została wprowadzona funkcja pozwalająca na wybranie jednego, konkretnego użytkownika, którego autoryzacja będzie wykorzystywana do wysyłki faktur przez API.

Operacja ta jest dostępna w zakładce PRZYCHODY » KSEF I INTEGRACJE » ZAAWANSOWANE. W danym miejscu użytkownik posiadający aktywną autoryzację z KSeF może zaznaczyć opcję UDOSTĘPNIJ MOJĄ AUTORYZACJĘ DO POŁĄCZEŃ API. Gdy co najmniej jeden użytkownik wyrazi powyższą zgodę, administrator konta będzie mógł wybrać osobę z listy rozwijanej w sekcji UŻYTKOWNIK DO AUTORYZACJI API. Po wskazaniu konkretnej osoby, system będzie wysyłać każdą fakturę z API do KSeF przy użyciu jej poświadczeń. Dzieje się to automatycznie, niezależnie od tego, do kogo należy klucz API użyty w danej integracji. 

System automatycznie przywróci ustawienie "automatyczny wybór" w przypadku, gdy wybrany wcześniej użytkownik:

• odznaczy opcję dotyczącą udostępnienia autoryzacji,
• usunie swoją autoryzację KSeF z systemu wFirma,
• zostanie odpięty od konta danej firmy.

Wysyłka wsadowa faktur

W systemie proces przesyłania dokumentów do KSeF odbywa się w pełni automatycznie. Częstotliwość wysyłki jest dynamicznie dostosowywana do liczby dokumentów oczekujących w kolejce.

Harmonogram wysyłki dokumentów

System sprawdza kolejkę dokumentów na firmie i dokonuje wysyłki faktur do KSeF w następujących interwałach:

• co 10 minut – jeżeli w kolejce do wysyłki znajduje się mniej niż 5 faktur;
• co 5 minut – jeżeli w kolejce oczekuje 5 lub więcej faktur.

Jak skonfigurować pobieranie przez API numeru KSeF faktur sprzedaży lub wysyłkę do KSeF?

Wysyłka faktur sprzedaży do Krajowego Systemu e-Faktur za pośrednictwem API odbywa się automatycznie w momencie ich utworzenia w systemie wFirma. Warunkiem automatycznej wysyłki jest włączenie odpowiedniej opcji w konfiguracji integracji oraz posiadanie aktywnej autoryzacji w KSeF (wgranego certyfikatu) przez użytkownika, którego klucz API został użyty do połączenia. Aktualnie przez API nie ma możliwości wystawiania wersji roboczych faktur, dlatego dokumenty są przesyłane do systemu ministerialnego natychmiast.

Pobranie numeru KSeF wygenerowanej faktury jest możliwe na dwa sposoby:

Poprzez API: Należy wywołać zasób /invoices/get/id_faktury. W odpowiedzi zostaną zwrócone informacje o statusie wysyłki. W przypadku pozytywnego przetworzenia (status 200), odpowiedź będzie zawierać parametry takie jak ksef_reference_number (numer nadany przez KSeF), ksef_registration_date oraz ksef_status. Parametry te nie są zwracane bezpośrednio w odpowiedzi na żądanie dodania faktury (/invoices/add), ponieważ system w tym momencie oczekuje jeszcze na przetworzenie dokumentu przez serwery Ministerstwa Finansów.

Poprzez Webhook: Po pomyślnym przetworzeniu faktury lub zwróceniu błędu przez KSeF, system automatycznie wyśle żądanie z informacją o statusie i numerze KSeF pod wskazany adres.

Aby skonfigurować webhook, należy:

1. Przejść do zakładki USTAWIENIA » INNE » WEBHOOKS
2. Dodać nowy webhook i wybrać zdarzenie Faktury KSeF » Zmiana statusu przetwarzania
3. Wprowadzić odpowiedni adres docelowy URL i zapisać zmiany.

Obsługa wersji roboczych faktur sprzedaży w systemie wFirma.pl

System wFirma.pl umożliwia obsługę faktur roboczych (draftów) za pośrednictwem interfejsu API. Funkcjonalność ta pozwala na przygotowanie wstępnych wersji dokumentów w systemie, które nie posiadają jeszcze nadanego numeru księgowego i nie są przesyłane do KSeF. Dzięki temu można swobodnie zarządzać danymi faktury (VAT, bez VAT oraz marża) przed ich ostatecznym wystawieniem.

Dodawanie wersji roboczej faktury sprzedaży po API

Aby dodać fakturę w wersji roboczej, należy skorzystać z metody POST na endpoint /invoices/add. Kluczowym elementem jest wskazanie odpowiedniego typu dokumentu.

W body zapytania, w polu type należy wprowadzić jedną z poniższych wartości:

• normal_draft – dla faktury VAT,
• bill_draft – dla faktury bez VAT,
• margin_draft – dla faktury marża.

Pobieranie danych faktury roboczej

W celu pobrania szczegółowych informacji o zapisanej wersji roboczej faktury należy wykorzystać metodę GET dla endpointa /invoices/get/{id}, gdzie {id} to unikalny identyfikator dokumentu nadany przez system. W odpowiedzi system zwróci pełną strukturę danych dokumentu, uwzględniając jego roboczy status.

Edycja faktury roboczej

Istniejące wersje robocze faktur mogą być modyfikowane za pomocą metody PUT dla endpointa /invoices/edit/{id}. Edycja pozwala na aktualizację:

• danych kontrahenta,
• pozycji na fakturze (produkty/usługi),
• dat oraz warunków płatności.

Dokument po edycji nadal zachowuje status roboczy i nie wpływa na numerację faktur w systemie.

Dodatkowe informacje

Wersje robocze faktur utworzone przez API charakteryzują się następującymi właściwościami:

• Brak numeru: Dokumenty te nie zajmują numeru w serii numeracji aż do momentu ich zatwierdzenia w interfejsie systemu wFirma.pl.
• Brak wysyłki do KSeF: Faktury w wersji roboczej nie są automatycznie przesyłane do Krajowego Systemu e-Faktur.
• Widoczność w systemie: Po dodaniu przez API, dokumenty są widoczne w zakładce PRZYCHODY » SPRZEDAŻ.