W erze cyfrowej transformacji dostęp do funkcjonalnych i elastycznych narzędzi dla przedsiębiorców i księgowych jest kluczowy. System wfirma.pl, będący zaawansowaną platformą m.in. do fakturowania i księgowości, otwiera nowe możliwości dzięki dostępowi do API.
API - interfejs dla programistów
Szczegółowa dokumentacja znajduje się pod adresem https://doc.wfirma.pl.
Zasada działania autoryzacji API w KSeF 2.0
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ą 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 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.
Jak poprawnie skonfigurować użytkownika API?
Aby uniknąć problemów z wystawianiem faktur, należy upewnić się, że użytkownik techniczny (obsługujący API) posiada pełną autoryzację.
Zaloguj się na konto użytkownika, którego klucz API jest wykorzystywany w integracji.
Przejdź do zakładki PRZYCHODY » KSEF.
W sekcji konfiguracji upewnij się, że status integracji jest aktywny.
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.
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Ż.
