Klucz o ograniczonym zasięgu
Dostęp do API daje klucz wydany dla konkretnej firmy i konkretnego zakresu uprawnień. Integracja czytająca faktury sprzedaży nie ma dostępu do kadr ani do rozliczeń podatkowych, a klucz można unieważnić bez naruszania pozostałych połączeń. W biurze rachunkowym obsługującym wiele firm ma to znaczenie podstawowe: klucz wydany dla jednego klienta nie sięga danych pozostałych.
Co da się zrobić przez interfejs
| Obszar | Typowe zastosowanie |
|---|---|
| Sprzedaż | Utworzenie faktury z zamówienia w sklepie albo systemie branżowym. |
| Kontrahenci | Zakładanie i aktualizacja kartotek odbiorców na podstawie danych z aplikacji. |
| Dokumenty zakupu | Przekazanie dokumentów z zewnętrznego obiegu do zaksięgowania. |
| Płatności | Odczyt statusu rozliczenia faktury, żeby aplikacja wiedziała, co zostało zapłacone. |
Integracja nie omija zasad księgowych. Dokument utworzony przez API przechodzi te same kontrole co wprowadzony ręcznie — numerację, walidację danych, kontrolę zamkniętego okresu. System nie ma osobnego, luźniejszego trybu dla maszyn.
Ograniczenia tempa
Interfejs ma limity liczby żądań, które chronią stabilność systemu przy masowych operacjach. Poprawnie napisana integracja traktuje odpowiedź o przekroczeniu limitu jako informację o tempie, a nie awarię, i ponawia żądanie po wskazanym czasie.
Od czego zacząć
Najpierw warto ustalić kierunek przepływu i to, który system jest źródłem prawdy dla danej informacji — kto zakłada kontrahenta, kto nadaje numer dokumentu, co się dzieje przy korekcie. Bez tego integracja działa do pierwszego rozjazdu danych. Napisz do nas, a przejdziemy przez to razem: kontakt.
Typowe zastosowania
- Sklep albo system sprzedaży przekazuje zamówienia, które stają się fakturami.
- System magazynowy pyta o stany i rezerwacje przed potwierdzeniem dostępności.
- Aplikacja terenowa wystawia dokument sprzedaży u klienta i od razu wysyła go do KSeF.
- Narzędzie raportowe pobiera dane finansowe do własnych zestawień.
- System kadrowy przekazuje dane do naliczenia wynagrodzeń.
Uwierzytelnianie i zakres uprawnień
Klucz wydaje się dla konkretnej firmy i konkretnego zakresu — osobno do odczytu, osobno do zapisu, osobno dla poszczególnych obszarów. Dzięki temu integracja sklepu, która ma jedynie zakładać dokumenty sprzedaży, nie dostaje dostępu do kadr ani do rozliczeń podatkowych. Klucz da się unieważnić bez ruszania pozostałych, a każde użycie zostawia wpis z czasem i adresem źródłowym.
Klucz w kodzie aplikacji klienckiej to klucz publiczny. Interfejs wywołuje się z serwera, nie z przeglądarki użytkownika ani z aplikacji mobilnej wysyłanej na urządzenia. Jeżeli integracja wymaga działania po stronie klienta, poprawnym wzorcem jest pośrednik na własnym serwerze, który trzyma klucz i przekazuje tylko to, co konieczne.
Jak reagować na błędy
Integracja, która działa, to integracja, która poprawnie zachowuje się przy niepowodzeniu. Odpowiedź niosąca błąd walidacji wskazuje pole i powód — taki błąd nie ma sensu powtarzać bez poprawienia danych. Inaczej jest przy błędach przejściowych i przy ograniczeniu tempa: tu właściwą reakcją jest ponowienie po odczekaniu, z rosnącym odstępem. Operacje tworzące dokumenty przyjmują własny identyfikator żądania, dzięki czemu powtórzenie tego samego wywołania nie tworzy drugiej faktury.
Wersjonowanie i zmiany
Zmiany rozszerzające — nowe pola w odpowiedzi, nowe operacje — pojawiają się bez zapowiedzi i integracja powinna je ignorować, jeżeli ich nie używa. Zmiany, które mogłyby zepsuć działające połączenie, trafiają do nowej wersji interfejsu, a poprzednia działa dalej przez ustalony okres. Dlatego klient powinien czytać pola po nazwie, a nie po pozycji, i nie zakładać, że odpowiedź nie urośnie.
Środowisko testowe
Integrację buduje się na danych testowych, na osobnej firmie, bez ryzyka wystawienia dokumentu do KSeF czy wysyłki deklaracji. Dopiero sprawdzony przepływ przełącza się na dane produkcyjne — przez zmianę klucza, nie przez zmianę kodu.