inFakt API: integracja sklepu i Allegro z fakturowaniem

inFakt API to interfejs REST w wersji 3, przez który program albo sklep internetowy wystawia faktury na Twoim koncie inFakt, pobiera PDF, oznacza płatności i zleca wysyłkę do KSeF. Dostęp daje klucz z ustawień konta, przekazywany w nagłówku X-inFakt-ApiKey.

Dokumentacja inFakt opisuje każde wywołanie z osobna. Nie mówi jednak, jak ułożyć z nich bezpieczny przebieg „zamówienie, faktura, płatność, KSeF” ani które błędy kosztują najwięcej. Ten przewodnik łączy jedno z drugim: dla sprzedawcy, który wybiera rozwiązanie, i dla programisty, który je buduje.

Co to jest inFakt API i co da się przez nie zrobić

API oparte jest na REST i wymianie danych w JSON. Produkcja działa pod adresem https://api.infakt.pl/api/v3, a połączenie idzie przez HTTPS z TLS 1.2 albo 1.3. Opis wszystkich zasobów znajdziesz w interaktywnej dokumentacji i w repozytorium inFakt na GitHubie.

Dla sklepu internetowego najważniejsza jest sekcja przychodów. Poza fakturami VAT obejmuje korekty, faktury zaliczkowe i końcowe, faktury marża i OSS, raporty fiskalne oraz dowody wewnętrzne.

Każdy zakres danych ma osobne uprawnienie. Odczyt i zapis faktur to api:invoices:read i api:invoices:write, a zarządzanie integracją z KSeF to api:ksef:integration:write. Osobno nadajesz dostęp do kosztów, księgowości i rachunków bankowych.

inFakt API dokumentacja: od czego zacząć

Zacznij od trzech miejsc. Każde odpowiada na inne pytanie.

1. docs.infakt.pl to interaktywna dokumentacja wywołań z parametrami i przykładowymi odpowiedziami.
2. github.com/infakt/API to ta sama wiedza w formie tekstu: punkty dostępu, uprawnienia, limity, kody błędów i filtrowanie.
3. Plik o KSeF opisuje wysyłkę faktur, statusy i różnice między starszą i nowszą wersją integracji.

Czytaj uważnie uwagi pod opisami wywołań. To w nich stoją zasady, które zmieniają działanie programu, na przykład to, że pobranie PDF zmienia status faktury.

Klucz API inFakt i konto testowe

Jak wygenerować klucz

1. Zaloguj się do inFakt w przeglądarce.
2. Wejdź w Ustawienia, Inne opcje, API.
3. Utwórz klucz i zaznacz potrzebne zakresy uprawnień.
4. Skopiuj klucz i zapisz go w bezpiecznym miejscu, poza kodem strony.
5. Sprawdź połączenie prostym odczytem listy faktur.

Klucz dołączasz do każdego zapytania w nagłówku HTTP:

curl -H "X-inFakt-ApiKey: TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  https://api.infakt.pl/api/v3/invoices.json

Klucz daje pełny dostęp w ramach nadanych zakresów, więc traktuj go jak hasło do księgowości. Nie wklejaj go do kodu, który trafia do przeglądarki klienta, i nie wysyłaj go e-mailem.

Sandbox inFakt: testy na osobnym koncie

inFakt udostępnia darmowe konto testowe pod adresem https://api.sandbox-infakt.pl/api/v3. Zakładasz je osobno, przez formularz rejestracji sandboxa. Konto przyjmie do 2500 faktur miesięcznie, a dane firmowe są w nim zanonimizowane.

Według dokumentacji API działa tam identycznie jak na produkcji. Masz jednak dostęp tylko do sekcji przychodów i ustawień. Koszty i księgowość przetestujesz dopiero na prawdziwym koncie.

Jak wystawić fakturę przez API inFakt krok po kroku

Faktury nie tworzysz jednym wywołaniem. inFakt przyjmuje zlecenie, przetwarza je w tle i dopiero potem zwraca dokument. Pełny przebieg dla zamówienia ze sklepu wygląda tak:

1. Zlecenie. Wysyłasz dane faktury na POST /async/invoices.json. Kwoty podajesz w groszach jako liczby całkowite.
2. Numer zadania. inFakt odpowiada kodem 202 („Zlecenie przyjęte”) i numerem zadania w polu invoice_task_reference_number.
3. Sprawdzenie statusu. Odpytujesz GET /async/invoices/status/{numer}.json, aż zadanie się zakończy i dostaniesz identyfikator faktury.
4. Szkic. Faktura zawsze powstaje jako szkic. Od tej chwili możesz ją zatwierdzić, wysłać albo oznaczyć jako zapłaconą.
5. Płatność. Oznaczasz fakturę jako zapłaconą. Data zapłaty nie może być wcześniejsza niż data wystawienia.
6. Dokument dla kupującego. Pobierasz PDF albo wysyłasz fakturę e-mailem prosto z inFakt.
7. KSeF. Zlecasz wysyłkę do KSeF i czekasz na status końcowy.

Dwa szczegóły z tej listy zaskakują najczęściej. Pierwszy to kwoty: 500000 w polu ceny oznacza 5000,00 zł. Drugi to brutto. Jeśli sklep ma ceny brutto, podaj w pozycji gross_price bez ceny netto, a inFakt sam wyliczy netto i VAT. Suma faktury zgodzi się wtedy z kwotą zapłaconą przez kupującego.

Oznaczenie płatności też jest zleceniem asynchronicznym. Kod 201 oznacza tylko przyjęcie zlecenia, a nie opłacenie faktury. Wynik trzeba potwierdzić odczytem dokumentu.

Limity zapytań i kody błędów inFakt API

inFakt ogranicza liczbę zapytań z jednego adresu IP, a nie z jednego klucza. To ważne, gdy na tym samym serwerze działa kilka skryptów albo kilka sklepów: wszystkie dzielą jedną pulę.

Kody błędów, które integracja musi rozpoznawać:

• 429: przekroczony limit zapytań. Odczekaj i zwolnij tempo, zamiast ponawiać od razu.
• 402: przekroczony limit planu konta inFakt.
• 403: brak uprawnień albo blokada adresu IP.
• 422: błąd walidacji, na przykład brak wymaganych danych kupującego.
• 423: zasób zablokowany do zmian.
• 503: serwis chwilowo niedostępny.

Integracja inFakt z KSeF przez API

Zanim wyślesz fakturę do KSeF przez API, konto inFakt musi mieć podłączony KSeF. W nowszej wersji integracji (/ksef2/) podłączenie robisz w aplikacji inFakt, a przez API sprawdzasz tylko jego stan.

Samą wysyłkę zlecasz dla jednej faktury albo dla wielu naraz. Według dokumentacji KSeF w inFakt faktura przechodzi przez trzy statusy:

Status końcowy sprawdzisz osobnym wywołaniem albo dostaniesz go webhookiem. inFakt sam zachęca do webhooka, bo ogranicza on liczbę zbędnych zapytań o status. Przez API pobierzesz też plik XML faktury i zaimportujesz faktury z KSeF do inFakt.

Pamiętaj, że wysyłki do KSeF nie cofniesz. Zlecaj ją dopiero dla faktury zatwierdzonej, a nie dla szkicu, który ktoś jeszcze poprawia. O tym, kogo i od kiedy dotyczy KSeF, piszemy w artykule faktury KSeF w e-commerce.

Webhooki inFakt: powiadomienia zamiast odpytywania

inFakt wysyła webhooki o zdarzeniach, na przykład o utworzeniu faktury albo o końcowym statusie wysyłki do KSeF. Webhook dodajesz w aplikacji inFakt, a nie przez API.

Webhook traktuj jak sygnał, a nie źródło danych. Po powiadomieniu odczytaj dokument swoim kluczem i dopiero wtedy zmień stan u siebie. Zostaw też zwykłe sprawdzanie statusu jako drogę zapasową. Gdy powiadomienie nie dotrze, faktura i tak trafi do Twojego programu przy najbliższym odpytaniu.

Własna integracja z inFakt API czy gotowy program

Prosty skrypt wystawiający fakturę po opłaceniu zamówienia napiszesz w kilka dni. Większość pracy przychodzi jednak później: przy limitach, korektach, błędach walidacji i KSeF.

Własny skrypt ma sens, gdy masz jeden kanał sprzedaży, nietypowy proces i programistę na stałe. Gotowa integracja wygrywa, gdy sprzedajesz w kilku miejscach, a faktury mają powstawać według tych samych zasad dla Allegro, Erli i sklepu.

Integracja inFakt z Allegro i sklepem w Berlinettcie

Berlinetta łączy się z Twoim kontem przez inFakt API. Zamówienia z Allegro, Erli i Twojego sklepu masz na jednej liście, a fakturę do każdego z nich wystawiasz w swoim inFakcie. Szczegóły podłączenia opisuje strona integracji z inFakt.

• Z karty zamówienia. Fakturę wystawiasz przyciskiem „Wystaw w inFakt”.
• Masowo. Z listy zamówień wystawisz do 100 faktur naraz. Zamówienia bez kompletu danych program pominie i poda powód.
• Regułą. Reguła automatyzacji utworzy fakturę sama, gdy zamówienie spełni ustawione przez Ciebie warunki.
• Kwoty bez przeliczania. Pozycje, stawki VAT i koszt dostawy przechodzą z zamówienia, a suma zgadza się z kwotą zapłaconą przez kupującego.
• Twoja numeracja. Numer nadaje inFakt, a faktura z jego PDF wraca do Dokumentów przy zamówieniu.
• Bez drugiej faktury. Ta sama faktura nie powstanie dwa razy, nawet po podwójnym kliknięciu.
• Płatność. Opłacone zamówienie oznacza fakturę jako zapłaconą.
• Korekta. Korektę ilości wystawisz z karty dokumentu.
• KSeF. Możesz zaznaczyć, żeby inFakt wysłał fakturę do KSeF zaraz po wystawieniu, a status KSeF wraca do Dokumentów.

Domyślnie w inFakcie powstaje szkic, który zatwierdzasz przyciskiem „Zatwierdź w inFakt”. W ustawieniach przełączysz wystawianie na faktury gotowe od razu. Klucz inFakt program przechowuje w sejfie i nie pokazuje go już nikomu. Zapytania do inFakt program sam rozkłada w czasie, więc masowe wystawianie nie wyczerpuje limitu.

Więcej o dokumentach znajdziesz na stronie dokumenty i faktury. Jeśli rozważasz inny system fakturowy, porównaj go z API wFirmy.

Z praktyki: błędy, które kosztują najwięcej przy inFakt API

Te przypadki zmierzyliśmy na koncie testowym inFakt, budując integrację. Każdy z nich przechodzi testy na pojedynczej fakturze i wychodzi dopiero przy prawdziwym ruchu.

1. Ponowione zlecenie po zerwanym połączeniu. Odpowiedź nie dotarła, ale faktura mogła powstać. Ślepe ponowienie daje drugą fakturę z kolejnym numerem. Najpierw sprawdź w inFakt, czy dokument istnieje.
2. PDF szkicu pobrany „na podgląd”. Pobranie PDF zmienia status faktury na „Wydrukowano”. Szkic wygląda wtedy dla księgowej jak dokument gotowy.
3. Data zapłaty sprzed wystawienia. Zamówienie z marketplace’u jest zwykle opłacone przed fakturą. Gdy wpiszesz datę wpłaty, inFakt odrzuci płatność. Datą zapłaty jest wtedy dzień wystawienia.
4. Przelew bez konta bankowego. Faktura płatna przelewem wymaga konta bankowego zapisanego w inFakt. Bez niego dostaniesz błąd 422.
5. Osoba prywatna bez adresu. Faktura dla osoby prywatnej z samym imieniem i nazwiskiem nie przejdzie. Wystarczą miasto i kod pocztowy.
6. Usunięty szkic. Numer usuniętego szkicu inFakt nada następnej fakturze. Jeśli zapisałeś go u siebie, dwa dokumenty będą miały ten sam numer.

Najdroższe w integracji z systemem fakturowym nie jest samo wystawienie faktury. Najdroższy jest dokument, który powstał dwa razy, albo ten, o którego istnieniu program nie wie. Dlatego każde zlecenie zapisuj u siebie przed wywołaniem API, a wynik zawsze potwierdzaj odczytem.