FakturaXL - integracja API: eksport CSV i faktury UBL 2.1

Punkt wyjścia

Dane w programie do fakturowania są, tylko nie da się ich stamtąd wyjąć w formie, której potrzebuje ktoś z zewnątrz - arkusz z produktami i aktualnym stanem magazynowym. Program pokazuje jedno i drugie, ale w osobnych widokach.

API stawia dwie przeszkody naraz. Produkty i stany magazynowe to dwa endpointy, każdy zwracający dane po stronie, a limit przepuszcza jedno zapytanie na dziesięć sekund. Zebranie pełnego katalogu to więc kilkanaście minut cierpliwego odpytywania, a nie jedno wywołanie.

Decyzje, które ukształtowały projekt

Jeden plik zamiast projektu

Backend, style i cały interfejs siedzą w jednym index.php. Bez frameworka, bez instalacji, bez katalogu z zależnościami - uruchamia się wbudowanym serwerem PHP i działa. Narzędzie, którego używa się kilka razy w miesiącu, nie może wymagać przypominania sobie, jak je postawić. To ten sam typ zadania, co inne nasze aplikacje webowe robione pod jedną konkretną robotę, a nie pod portfolio technologii.

Limit zapytań jako część projektu, nie jako awaria

Dziesięć sekund między zapytaniami to nie błąd do obejścia, tylko warunek brzegowy. Eksport odczekuje między stronami, rozpoznaje odpowiedź „przekroczono limit” i ponawia zapytanie po dodatkowej przerwie zamiast przerywać z błędem. Przez cały czas pokazuje, przy której stronie jest.

Alternatywa, czyli walenie w API do skutku, kończy się blokadą tokenu i eksportem urwanym w połowie. To właśnie ten rodzaj roboty - przejście przez dziesiątki stron API zamiast ręcznego klikania w panelu - ma sens jako automatyzacja, a nie jako kolejna czynność na liście rzeczy do zrobienia co miesiąc.

Sklejanie dwóch list po właściwym kluczu

Produkt i jego stan magazynowy trzeba dopasować po identyfikatorze, a nie po nazwie czy pozycji na liście. Zero sztuk zapisuje się jako zero, nie jako puste pole - w arkuszu to różnica między „nie ma na stanie” a „nie wiadomo”. Gdy strona produktów nie ma ani jednego dopasowania do pobranej strony stanów, interfejs proponuje przeszukanie pozostałych stron zamiast pokazywać pustą tabelę.

Kody błędów przetłumaczone na zdania

API odpowiada numerami. Aplikacja trzyma mapę tych kodów i pokazuje „nieprawidłowy token” albo „przekroczono limit zapytań, poczekaj chwilę”, bo komunikat kod=3 nie mówi użytkownikowi nic o tym, co ma zrobić.

Druga część: faktura ustrukturyzowana

Osobny wątek u tego samego klienta to eksport faktury do XML w standardzie UBL 2.1, w profilu Peppol BIS Billing 3.0. Plik albo przechodzi walidację normy, albo jest bezużyteczny - nie ma wersji „prawie zgodnej”.

Robota polegała na przejściu pola po polu przez wymagania normy: identyfikatory profilu, kody schematu przy numerach podatkowych, NIP z prefiksem kraju tam, gdzie standard go wymaga, i bez prefiksu tam, gdzie nie. Sekcje identyfikacyjne i podatkowe znikają, gdy kontrahent nie ma NIP-u, zamiast trafiać do pliku wypełnione samym prefiksem kraju - puste pole zawsze jest lepsze od pola z czymś, co tylko wygląda jak dane. Doszły dane płatności z numerem rachunku, osobny adres odbiorcy przy wysyłce pod inny adres oraz stawki zwolniona, niepodlegająca i odwrotne obciążenie, które w tym standardzie nie są procentami, tylko osobnymi kategoriami podatkowymi.

Każda wersja pliku szła przez zewnętrzny walidator Peppol, a nie przez „wygląda dobrze”.

Co z tego wyszło

Tu nie mamy z czego zrobić tabeli pomiarów - FakturaXL nie ma publicznego adresu, więc pomiar strony jest niewykonalny, a dane z produkcji klienta (ile razy narzędzie odpaliło eksport, jak długo trwał na pełnym katalogu) nie są nam znane. Zostaje efekt jakościowy: eksport produktów i stanów magazynowych, który wcześniej wymagał ręcznego przechodzenia przez dwa osobne widoki API, jest teraz jednym uruchomieniem i jednym plikiem CSV. Faktura w UBL 2.1 przechodzi walidację normy Peppol zamiast wracać z listą błędów.

Uczciwie: nie wiemy, ile czasu to realnie oszczędza u klienta - nie mierzyliśmy procesu sprzed integracji i nie mamy dostępu do logów z jego produkcji.

Technicznie

PHP 8 z curl i simplexml, komunikacja z API przez POST z ciałem XML, front jako SPA w czystym JavaScripcie w tym samym pliku. Eksport CSV z separatorem średnikowym, żeby arkusz otworzył go bez zabawy w import. Generator UBL to osobny skrypt PHP po stronie programu, sprawdzany na oficjalnych przykładach standardu i na fakturach z realnymi danymi.