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Ż.

Regulamin API 

Każdy korzystający z API przyjmuje zasady opisane w regulaminie

§ 1. POSTANOWIENIA OGÓLNE

Niniejszy Regulamin określa zasady i warunki korzystania z usługi API, świadczonej drogą elektroniczną przez Usługodawcę, umożliwiającej zdalne łącznie serwisu wFirma.pl za pomocą zewnętrznych systemów teleinformatycznych, w celu sprawniejszego zastosowania usług świadczonych przez Usługodawcę tj. przeznaczone jest dla deweloperów budujących rozwiązania zintegrowane z systemem wFirma. Korzystanie z API możliwe jest jedynie na zasadach określonych niniejszym Regulaminem.

§ 2. DEFINICJE

1. Regulamin główny - regulamin dostępny pod adresem: https://pomoc.wfirma.pl/-regulamin-swiadczenia-uslug.

2. Regulamin - niniejszy regulamin stanowiący załącznik do Regulaminu głównego.

3. Serwis - serwis wFirma.pl pod adresem: https://wfirma.pl/, prowadzony przez Usługodawcę.

4. Usługobiorca - Przedsiębiorca, korzystający z Serwisu na podstawie Regulaminu głównego. 

5. Usługodawca - Web INnovative Software Spółka z ograniczoną odpowiedzialnością z siedzibą we Wrocławiu, ul. Bierutowska 57-59, 50-545 Wrocław, wpisana do Rejestru Przedsiębiorców Krajowego rejestru Sądowego prowadzonego przez Sąd Rejonowy dla Wrocławia-Fabrycznej we Wrocławiu, VI Wydział Gospodarczy Krajowego Rejestru Sądowego, pod nr KRS - 0000342082; NIP: 8982167294, REGON: 021120771, posiadająca kapitał zakładowy w kwocie 1 260 000,00 zł, adres e-mail: biuro@wfirma.pl.

6. Użytkownik - osoba posiadająca konto w Serwisie, upoważniona do reprezentowania Usługobiorcy.

7. API – usługa świadczona przez Usługodawcę na rzecz Usługobiorców, umożliwiająca korzystanie z interfejsu dostępowego, wykorzystującego protokół elektronicznej wymiany danych, umożliwiający komunikację Oprogramowania z zasobami (modułami) Serwisu.

8. Oprogramowanie - oprogramowanie będące we władaniu Usługobiorcy, które wykorzystuje API.

9. Zestaw Danych Autoryzacyjnych – ustanowiony na rzecz Usługobiorcę indywidualny identyfikator oraz hasło (klucz API) umożliwiający dostęp oraz korzystanie z API.

§ 3 ZASADY UDZIELANIA DOSTĘPU DO API

1. Złożenie wniosku o uzyskanie dostępu do API oraz każdorazowe użycie API odbywa się w ramach Regulaminu oraz Regulaminu Głównego, przy czym może także odbywać się  na podstawie odrębnej umowy zawartej z Usługobiorcą.

2. Usługobiorca ma prawo złożyć wniosek o uzyskanie dostępu do API, poprzez użycie w Serwisie zakładki „integracja z API”. Skorzystanie z zakładki „Integracja z API” umożliwia Usługobiorcy wygenerowanie Zestawu Danych Autoryzacyjnych.

3. Usługobiorcy, którzy uzyskali Zestaw Danych Autoryzacyjnych, o którym mowa w ust. 2 powyżej, ponoszą wszelką odpowiedzialność za jego wykorzystanie, w tym w szczególności za jego wykorzystywanie w celach sprzecznych z obowiązującym prawem, dobrymi obyczajami, zasadami współżycia społecznego oraz Regulaminem. 

4. Usługobiorca jest zobowiązany do zabezpieczenia dostępu do Zestawu Danych Autoryzacyjnych w taki sposób, by nie miały do niego dostępu osoby trzecie. Odpowiedzialność Usługobiorcy rozciąga się również na działania osób, którym Zestaw Danych Autoryzacyjnych został udostępniony w wyniku działania lub zaniechania Usługobiorcy, nawet w sposób niezawiniony.

5. Usługodawca ma prawo odmowy przyznania Zestawu Danych Autoryzacyjnych bądź ich unieważnienia, w szczególności jeśli Usługobiorca może choćby potencjalnie naruszać interesy Usługodawcy bądź jego klientów lub kontrahentów, albo jeżeli może być on wykorzystywany w sposób sprzeczny z zapisami § 4 ust. 4.

6. Wykorzystanie API jest uzależnione od weryfikacji uprawnień Usługobiorcy na podstawie przedstawienia prawidłowego Zestawu Danych Autoryzacyjnych oraz wydanych na jego podstawie innych danych dostępowych, które służą do autoryzacji czynności dokonywanych w Serwisie.

§ 4 WARUNKI KORZYSTANIA

1. Korzystanie z API może obywać się bezpłatnie do limitu 1000 wygenerowanych za pośrednictwem API dokumentów miesięcznie.

2. W przypadku przekroczenia limitu, o którym mowa w ust. 1 powyżej, Usługobiorca otrzyma elektroniczną informację o tym fakcie i zostanie mu wyświetlony formularz kontaktowy. Generowanie dalszych dokumentów będzie możliwe odpłatnie na podstawie indywidualnie zawartej umowy, opartej o indywidulaną wycenę tej Usługi. 

3. Możliwość generowania dalszych dokumentów powyżej limitu, o którym mowa w ust. 1, będzie możliwe jedynie w przypadku dysponowania przez Usługobiorcę aktywnymi dodatkami „Allegro” oraz „Menedżer e-commerce”. 

4. API nie może być wykorzystywane przez Usługobiorców do celów funkcjonowania Oprogramowania, które:

a) narusza powszechnie obowiązujące prawo oraz prawa osób trzecich,

b) narusza dobre obyczaje lub cel w jakim wFirma udostępnia API,

c) może wprowadzać użytkowników Internetu w błąd,

d) działa złośliwie lub na szkodę jakiegokolwiek podmiotu.

§ 5 ODPOWIEDZIALNOŚĆ ZA NARUSZENIE POWSZECHNIE OBOWIĄZUJĄCEGO PRAWA ORAZ PRAW OSÓB TRZECICH WYNIKŁYCH Z KORZYSTANIA Z API 

1. Rozpowszechnianie Oprogramowania, które w jakikolwiek sposób komunikuje się z innymi Użytkownikami, bądź uzależnione jest od podania bądź wykorzystania loginu i hasła innych Użytkowników, nie będących twórcami Oprogramowania, wymaga zgody Usługodawcy.

2. Osoby udostępniające Oprogramowanie zobowiązane są w każdym przypadku do podania Użytkownikom rzetelnej informacji dotyczącej zasad korzystania z Oprogramowania i polityce bezpieczeństwa dotyczącej danych jej użytkowników, która nie może zapewniać niższego poziomu ochrony danych osobowych niż Polityka Prywatności Portalu.

3. Odpowiedzialność za opracowanie, eksploatację, wspieranie aplikacji wykorzystujących API ponosi Usługobiorca.

4. Usługodawca dołoży wszelkich starań, aby zestaw metod API dostępnych dla Usługobiorców odpowiadał funkcjonalnościom Serwisu oraz był wolny od błędów. Nie mniej jednak użycie API odbywa na własne ryzyko Usługobiorcy na podstawie dokumentacji, opisu i informacji udostępnionej przez Usługodawcę.

5. W uzasadnionych przypadkach związanych z rażącymi brakami lub problemami technicznymi, w szczególności dotyczącymi bezpieczeństwa Serwisu lub działań konkurencyjnych na szkodę Usługodawcy, bądź też w przypadku wykoryztsania API do innych celów niż zostało ono udostępnione  Usługodawca zastrzega sobie prawo do blokady Zestawów Danych Autoryzacyjnych i wszystkich programów lub systemów korzystających z API.

6. W przypadku naruszenia niniejszego Regulaminu bądź Regulaminu Głównego Usługodawca ma prawo do zablokowania Usługobiorcy możliwości korzystania z wszelkich usług świadczonych przez Usługodawcę.

§ 6 POSTANOWIENIA KOŃCOWE

1. Usługodawca zastrzega sobie prawo do zmiany niniejszego Regulaminu. 

2. Zmiany Regulaminu wobec Usługobiorców, na rzecz których API świadczona jest odpłatnie, wchodzą w życie w terminie wskazanym przez Usługodawcę, nie krótszym niż 7 dni od dnia poinformowania ich drogą elektroniczną. 

3. W sprawach nieuregulowanych niniejszym Regulaminem stosuje się odpowiednio postanowienia Regulaminu Głównego