VulCode

Integracja Fakturownia i wFirma przez API

Faktura powstaje w programie, który zna Twoja księgowa, a dane do niej dostarcza Twój sklep, aplikacja albo Stripe. Do KSeF wysyła ją sam program, a numer KSeF i status wracają do Twojego systemu.

Faktury i ERP
Panel administracyjny z fakturami z Fakturowni: statusy KSeF z pola gov_status, dzisiejsze faktury z reakcją na każdy status i droga jednej faktury od płatności do numeru KSeF

KSeF po stronie programu czy po stronie Twojego kodu

To pierwsza decyzja. Przy Fakturowni i wFirmie zwykle wygrywa program, ale nie zawsze.

Dane do faktury z Twojego sklepu, aplikacji albo Stripe

Kto wysyła fakturę do KSeF?

Program wysyła do KSeF

Kiedy
  • Księgowość i tak pracuje w Fakturowni albo wFirmie.
  • Chcesz jednego miejsca na faktury, korekty i ich statusy w KSeF.
  • Twój system ma tylko dostarczyć dane i odebrać numer KSeF.
Wniosek

Integracja z API programu: tworzymy fakturę ze zleceniem wysyłki do KSeF i odczytujemy jej status.

Twój system wysyła do KSeF

Kiedy
  • Faktury powstają w Twoim systemie i tam mają zostać.
  • Potrzebujesz pełnej kontroli nad kolejką, trybami offline i kodami QR.
Wniosek

Bezpośrednia integracja z API KSeF w Twoim kodzie, bez programu fakturowego po drodze.

Fakturownia i wFirma od strony API

Oba programy mają publiczne API, ale rozmawia się z nimi inaczej.

Ustawienia połączenia z wFirmą w panelu administracyjnym: trzy klucze API, secretKey bez możliwości odczytu, wybór firmy przez company_id i test połączenia

  1. Trzy klucze zamiast jednego tokenu

    Fakturownia łączy się tokenem API z ustawień konta. wFirma chce accessKey i secretKey z ustawień oraz appKey, który wydaje dla aplikacji, albo OAuth; wszystkie klucze trzymamy poza kodem.

  2. secretKey widać tylko raz

    wFirma wyświetla go tylko przy tworzeniu. Przekazujesz go nam od razu bezpiecznym kanałem albo tworzysz nowy.

  3. company_id w każdym zapytaniu

    W Fakturowni kolejna firma to osobna domena konta. W wFirmie bez company_id zapytanie może trafić do innej firmy użytkownika, więc ustawiamy go w każdym wywołaniu.

Zamówienie zamienione w fakturę

Mapowanie dla Fakturowni. Najwięcej uwagi wymaga nabywca, bo od niego zależy wysyłka do KSeF.

Zamówienie w Twoim systemie
Reguła
Faktura w Fakturowni
  1. Zamówienie w Twoim systemieklient firmowy z NIP
    →wymagane przy KSeF
    Faktura w Fakturownibuyer_company: true, buyer_tax_no
  2. Zamówienie w Twoim systemiefirma z UE z numerem VAT UE
    →numer w formacie unijnym
    Faktura w Fakturownibuyer_tax_no_kind: "nip_ue"
  3. Zamówienie w Twoim systemieosoba prywatna
    →buyer_company: false, bez NIP
    Faktura w Fakturownibuyer_first_name, buyer_last_name
  4. Zamówienie w Twoim systemiepozycja koszyka
    →nazwa i ilość
    Faktura w Fakturownipositions[].name, quantity
  5. Zamówienie w Twoim systemiekwota brutto i stawka
    →stawka jako liczba, np. 23
    Faktura w Fakturownitotal_price_gross, tax
  6. Zamówienie w Twoim systemienumer KSeF po wysyłce
    ←zapisywany z powrotem przy zamówieniu
    Faktura w Fakturownigov_id
Pole buyer_company
Decyduje o automatycznej wysyłce. W trybach dla firm program wysyła do KSeF tylko faktury z wartością true.
NIP nabywcy przy aktywnym KSeF
Jest wymagany dla firm, chyba że rodzaj numeru ustawiono na empty.
Dane nabywcy przy zakupie
Formularz zakupu pyta, czy klient kupuje jako firma, i zbiera NIP albo numer VAT UE.
Dane sprzedawcy, adresy i ustawienia konta uzupełniamy w konfiguracji, żeby nie powtarzać ich w każdym żądaniu.

Statusy KSeF w Fakturowni

Pole gov_status mówi, co dzieje się z fakturą. Każdy status ma w Twoim panelu swoją reakcję.

  1. Twój system

    Po opłaconej płatności tworzy fakturę z danymi nabywcy i pozycjami zamówienia.

    Na start
    faktura za abonament opłacony w Stripe

  2. Fakturownia

    Zapisuje fakturę z gov_save_and_send i sama zleca wysyłkę do KSeF.

    Z kroku 1
    dane nabywcy i pozycje

  3. KSeF

    Przyjmuje fakturę i nadaje jej numer. W Fakturowni gov_status przechodzi z processing na ok.

    Z kroku 2
    wysyłka do KSeF

  4. Twój system

    Odczytuje gov_status i numer gov_id webhookiem albo okresowym sprawdzeniem i zapisuje je przy zamówieniu.

    Z kroku 3
    numer i status

  • Gdy KSeF przyjmie fakturę

    Przyjęta przez KSeF. Zapisujemy numer gov_id i link weryfikacyjny do kodu QR.

  • Panel: faktury do poprawki

    Z kroku 3: send_error

    Błąd wysyłki. Pokazujemy treść z gov_error_messages, żeby dało się poprawić dane.

  • Gdy faktura wymaga poprawki

    Panel administracyjny pokazuje gov_status każdej faktury i listę tych, które wymagają poprawki.

processing

W trakcie wysyłki. Czekamy i sprawdzamy ponownie.

server_error

Błąd po stronie KSeF. Ponawiamy później, bez ingerencji w fakturę.

status_check_error

Nie udało się sprawdzić statusu, a faktura mogła już zostać przyjęta. Najpierw sprawdzamy, potem ewentualnie ponawiamy.

offline

Wystawiona w trybie offline, czeka na przekazanie do KSeF w ustawowym terminie.

duplicate_error

Faktura o tym numerze już jest w KSeF. Sprawdzamy, czy to nie ta sama faktura wysłana drugi raz.

not_connected

Konto nie jest połączone z KSeF. Potrzebna autoryzacja w programie, a nie zmiana w kodzie.

Pułapki, które sprawdzamy

Każda pochodzi z dokumentacji API obu programów.

  • Tryb DEMO przed produkcją

    Faktury w trybie DEMO trafiają do przedprodukcyjnego KSeF i mają statusy z przedrostkiem demo_. Tak testujemy całą ścieżkę.

    Przewodnik KSeF w API Fakturowni

  • Walidacja przed wysyłką

    Przy włączonej walidacji błędne dane zatrzymują zapis. Przy wyłączonej trafiają do gov_error_messages, które trzeba czytać.

    Przewodnik KSeF w API Fakturowni

  • Dokumenty spoza KSeF

    Proformy, paragony i inne dokumenty dostają status not_applicable. Nie traktujemy go jako błędu.

    Przewodnik KSeF w API Fakturowni

  • Numerowane gałęzie w JSON

    W formacie JSON gałęzie modułu muszą być numerowane, nawet gdy jest jedna. To częsty powód odrzuconych zapytań.

    Dokumentacja API wFirmy

Najczęstsze pytania

Odpowiedzi o wysyłce do KSeF, statusach, kluczach i kodzie integracji.

Czytaj dalej

Skąd przychodzą dane do faktur i dokąd trafiają.

Z czego mają powstawać Twoje faktury?

Napisz, skąd przychodzą zamówienia albo płatności i w którym programie pracuje księgowość. Odpowiemy w godzinę z pytaniami i wyceną.