Spis poradników

Ta sekcja jest dla sytuacji, w których znasz już ogólny kształt SDK i chcesz wykonać konkretne zadanie w KSeF. Szybki start pokazuje jedną ścieżkę od początku do końca; poniższe poradniki rozbijają typowe decyzje produkcyjne.

Konfiguracja

• Konfiguracja klienta: Sync albo async, publiczne moduły klienta bazowego i moduły po uwierzytelnieniu.
• Uwierzytelnij się: Wybierz certyfikat TEST, token KSeF, certyfikat XAdES, zmienne środowiskowe albo profile kompatybilne z CLI.
• Użyj profili: Współdziel lokalną konfigurację ksef2-cli z uwierzytelnianiem SDK i ProfileStore.

Faktury

• Zbuduj faktury FA(3): Wygeneruj prosty publiczny model faktury i XML FA(3) do wysyłki przez fluent builder.
• Wyślij faktury: Wyślij XML FA(3) przez sesję online albo sesję wsadową i sprawdź wynik przetwarzania.
• Sprawdź status i UPO: Odpytuj status online albo batch, listuj faktury sesji i pobieraj dokumenty UPO.
• Wyszukaj faktury: Zbuduj filtry metadanych, przejdź po stronach wyników i czekaj na widoczność nowych faktur.
• Pobierz faktury: Pobierz jedną fakturę po numerze KSeF albo zaplanuj szyfrowany eksport paczek.

Administracja

• Zarządzaj tokenami: Generuj, listuj, sprawdzaj i cofaj tokeny KSeF dla automatyzacji.
• Zarządzaj uprawnieniami: Nadawaj, wyszukuj, odbieraj i monitoruj uprawnienia KSeF.
• Zarządzaj certyfikatami: Sprawdzaj limity, rejestruj certyfikaty, pobieraj wydane materiały i cofaj certyfikaty.
• Zarządzaj limitami: Odczytuj i nadpisuj limity kontekstu, podmiotu oraz API rate limity.

Narzędzia pomocnicze

• Sprawdź certyfikaty szyfrowania: Sprawdzaj publiczne certyfikaty KSeF używane w szyfrowanych przepływach faktur i eksportów.
• Wyszukaj dostawców PEPPOL: Wyszukuj publiczne dane dostawców PEPPOL z klienta bazowego.
• Użyj danych TEST: Twórz sandboxowe podmioty, uprawnienia, flagi załączników i fixture'y z temporal cleanup.
• Użyj pomocników XAdES: Ładuj materiał certyfikatu, generuj certyfikaty TEST i podpisuj XML.
• API niskiego poziomu: Zejdź do schema-native wrapperów endpointów dla własnego podpisu, custody szyfrowania albo debugowania payloadów.

Typowa kolejność

1. Skonfiguruj środowisko i dane uwierzytelniające.

   Sekrety trzymaj w zmiennych środowiskowych, a niesekretne ustawienia w lokalnej konfiguracji.

2. Uwierzytelnij się dla wybranego kontekstu.

   Uwierzytelniony klient udostępnia online_session, batch, invoices, tokens, permissions, certificates i inne moduły przepływów.

3. Uruchom gałąź przepływu, która odpowiada za zadanie.

   Użyj publicznych modułów klienta bazowego do certyfikatów szyfrowania, lookupu PEPPOL i danych TEST. Użyj modułów uwierzytelnionych do faktur, sesji, tokenów, uprawnień, certyfikatów i limitów.

4. Poczekaj na przetwarzanie w KSeF albo status operacji.

   Pomocniki wysokiego poziomu potrafią odpytywać status faktury, zakończenie batcha, operacje uprawnień, rejestrację certyfikatu, widoczność w metadanych i gotowość paczki eksportu.

5. Zapisz wynik biznesowy.

   Zapisuj numery KSeF, referencje sesji, referencje operacji, uchwyty eksportu, pobrany XML, referencje tokenów, numery seryjne certyfikatów i UPO zgodnie z polityką retencji aplikacji.

Referencja

• Szybki start: Uruchom pierwszy przepływ generowania, wysyłki, potwierdzenia i pobrania.
• Operacje: Mapuj zadania na moduły SDK, pomocniki pollingu i granice ponawiania.
• Kontrakt publicznego API: Przejrzyj stabilne importy i publiczne moduły wystawiane przez SDK.
• Low-level API: Użyj schema-native wrapperów endpointów, gdy przepływ wysokiego poziomu nie wystarcza.