KSeF bez kodu – jak zintegrować API ksefservice.pl z Azure Logic Apps

Azure Logic Apps to usługa Microsoftu do budowania przepływów integracyjnych w sposób wizualny — bez pisania klasycznego kodu aplikacji. Dla firm, które mają już swoje procesy oparte na usługach Microsoft (Dynamics, SharePoint, SQL Server, Outlook, Power Platform), Logic Apps bywa naturalnym miejscem do spięcia tych systemów z zewnętrznym API — w tym z API ksefservice.pl. W tym artykule pokazujemy, jak to podejście wygląda w praktyce.

Czym są Azure Logic Apps — w skrócie

Logic Apps pozwalają budować przepływy (workflow) w formie graficznego diagramu: wyzwalacz (trigger) uruchamia sekwencję akcji, z których każda wykonuje konkretny krok — pobranie danych, przekształcenie ich, wywołanie zewnętrznego API, zapisanie wyniku. Więcej o samej usłudze i jej możliwościach znajdziesz w oficjalnej dokumentacji Microsoft Azure Logic Apps. Z perspektywy integracji z KSeF istotne jest to, że Logic Apps mają wbudowaną, ogólną akcję HTTP, pozwalającą wywołać dowolny endpoint REST API — a to wystarczy, żeby zintegrować się z ksefservice.pl bez pisania dedykowanego konektora.

Jak wygląda taki przepływ koncepcyjnie

Wyzwalacz (np. nowy rekord w SQL / SharePoint / Dynamics)
        ↓
Akcja: pobranie i przygotowanie danych faktury
        ↓
Akcja HTTP: POST do ksefservice.pl API (/invoices/fa3 lub /invoices/send)
        ↓
Akcja: odczyt odpowiedzi (numer KSeF, status)
        ↓
Akcja: zapis wyniku z powrotem w systemie źródłowym

Konfiguracja krok po kroku

1. Wybór wyzwalacza. Logic Apps oferują gotowe wyzwalacze dla wielu usług Microsoft — np. „gdy nowy wiersz zostanie dodany w SQL Server", „gdy nowy element pojawi się na liście SharePoint" czy „gdy nowe zamówienie pojawi się w Dynamics 365". Wybierasz ten, który odpowiada momentowi, w którym w Twoim procesie powinna powstać faktura.
2. Przygotowanie danych wejściowych. Za pomocą akcji „Compose" lub bezpośredniego mapowania pól budujesz strukturę danych faktury (sprzedawca, nabywca, pozycje, stawki VAT) na podstawie danych z wyzwalacza.
3. Dodanie akcji HTTP. Konfigurujesz akcję HTTP z metodą POST, adresem endpointu API ksefservice.pl (np. https://ksefservice.pl/api/v1/invoices/fa3), nagłówkiem Content-Type: application/json oraz treścią żądania zbudowaną w poprzednim kroku — zawierającą dane logowania (clientId, login, password) i środowisko (api_env).
4. Odczyt odpowiedzi. Logic Apps automatycznie parsuje odpowiedź JSON — możesz od razu odwołać się do konkretnych pól (np. numer KSeF) w kolejnych krokach, bez ręcznego pisania kodu parsującego.
5. Wysyłka dokumentu do KSeF. Analogiczna akcja HTTP, tym razem wywołująca endpoint wysyłki (/invoices/send), z plikiem XML wygenerowanym w poprzednim kroku.
6. Zapis wyniku. Ostatnia akcja zapisuje numer KSeF i status z powrotem w systemie źródłowym — np. aktualizując rekord w SQL Server czy dodając komentarz do zamówienia w Dynamics.

Obsługa błędów w Logic Apps

Logic Apps udostępniają mechanizm „Configure run after" pozwalający zdefiniować, co ma się wydarzyć w przypadku niepowodzenia danej akcji (np. błędu HTTP innego niż 200) — można w ten sposób zbudować rozgałęzienie: przy sukcesie zapisz numer KSeF, przy błędzie wyślij powiadomienie (np. e-mail albo wiadomość na Teams) do osoby odpowiedzialnej za monitorowanie procesu.

Zalety takiego podejścia

• Brak potrzeby pisania i utrzymywania kodu integracyjnego — cały przepływ konfigurowany jest wizualnie, co obniża próg wejścia dla zespołów bez dedykowanych programistów.
• Naturalna integracja z ekosystemem Microsoft — jeśli Twoje procesy już opierają się na Dynamics, SharePoint czy Power Platform, spięcie ich z KSeF przez Logic Apps nie wymaga wychodzenia poza znany ekosystem.
• Wbudowany monitoring przebiegu — Logic Apps prowadzą historię uruchomień każdego przepływu, co ułatwia diagnozę, gdy jakaś faktura nie została wysłana poprawnie.
• Skalowanie bez zmiany architektury — Logic Apps automatycznie skalują się wraz z liczbą uruchomień, bez potrzeby samodzielnego zarządzania infrastrukturą.

Na co zwrócić uwagę

• Bezpieczne przechowywanie danych logowania. Dane dostępowe do API (login, hasło, clientId) warto przechowywać w Azure Key Vault i odwoływać się do nich z Logic Apps, zamiast wpisywać je wprost w konfiguracji przepływu.
• Limity i ponawianie żądań. Logic Apps mają wbudowaną obsługę ponawiania (retry policy) dla akcji HTTP — warto ją skonfigurować świadomie, uwzględniając limity zapytań API KSeF, zamiast zostawiać wartości domyślne.
• Środowisko testowe na start. Tak jak przy każdej integracji z KSeF, budowę przepływu warto zacząć od parametru api_env=TEST, a dopiero po weryfikacji przełączyć na środowisko produkcyjne.

Dla kogo ma to sens

Integracja przez Azure Logic Apps ma sens dla firm korzystających już z usług Microsoft Azure lub Dynamics 365, które chcą zautomatyzować wysyłkę faktur do KSeF bez angażowania zespołu programistów do napisania i utrzymywania dedykowanej aplikacji integracyjnej. To też dobra opcja dla zespołów IT, które preferują niskokodowe (low-code) narzędzia do integracji nad pisaniem i wdrażaniem własnych mikroserwisów.

Podsumowanie

Dzięki ogólnej akcji HTTP dostępnej w Azure Logic Apps, integracja z API ksefservice.pl nie wymaga dedykowanego łącznika ani pisania kodu — wystarczy wizualnie skonfigurować przepływ: wyzwalacz, przygotowanie danych, wywołanie API, odczyt odpowiedzi i zapis wyniku. To podejście dobrze sprawdza się w środowiskach opartych na ekosystemie Microsoft, gdzie priorytetem jest szybkość wdrożenia i minimalizacja utrzymywanego kodu.

Chcesz skonfigurować taki przepływ dla swojej firmy? Skontaktuj się z nami lub sprawdź dokumentację API ksefservice.pl.