PSB posiada dwa hooki KSeF: hook outbound dla faktur wychodzących (strona sprzedająca / Podmiot1) oraz hook inbound dla faktur przychodzących (strona kupująca / Podmiot2). Oba automatyzują wymianę z Krajowym Systemem e-Faktur (KSeF), polskim krajowym systemem e-fakturowania. Hook outbound opisano poniżej jako pierwszy; hook inbound znajduje się na dole tej strony.

Hook outbound KSeF automatyzuje rejestrację faktur wychodzących w KSeF. Faktury są przekształcane z formatu Peppol BIS Billing 3.0 / UBL (wewnętrznie również BisV3) do polskiego formatu FA(3) i rejestrowane jako paczka (batch). Klient może również sam dostarczyć FA(3) — wtedy krok transformacji jest pomijany. Po pomyślnym przetworzeniu hook zwraca UPO (Urzędowe Poświadczenie Odbioru) oraz potwierdzenie w formacie PDF przez platformę PSB.

Do testów i odbioru administracja polska udostępnia dwa środowiska oprócz produkcyjnego:

Hook obsługuje zarówno tryb online (bezpośrednia rejestracja), jak i tryb offline (gdy KSeF jest tymczasowo niedostępny, na przykład podczas codziennego okresu przerwy). W trybie offline generowany jest PDF offline na podstawie certyfikatu offline.

• Ważny certyfikat online dla KSeF (.key + .crt; uwierzytelnianie podczas trybu online)
• Ważny certyfikat offline dla KSeF (.key + .crt; kody QR w wyjściowym PDF, zarówno przy przetwarzaniu online, jak i offline)
• Odpowiednie hasła do obu certyfikatów
• Hook musi być aktywowany w konfiguracji

Po otrzymaniu powiadomienia o fakturze hook przechodzi przez siedem kroków:

Gdy KSeF jest niedostępny (codzienny okres przerwy lub awaria), tryb offline uruchamia się automatycznie: generowany jest PDF offline za pomocą certyfikatu offline, po czym faktura jest wysyłana regularnym kanałem.

Proszę zarejestrować hook przez API Hooks:

{
  "id": "ksef-sender",
  "action": "ksef",
  "name": "KSeF Hook Sender",
  "topics": [
    "ClearInvoiceBatched"
  ],
  "output": [
    {
      "when": "200",
      "topic": "SendInvoice"
    },
    {
      "when": "410",
      "topic": "SendInvoice"
    }
  ],
  "init": {
    "onlineCertificate": "{{sciezka-do-certyfikatu-online}}",
    "onlineCertificatePassword": "{{haslo}}",
    "offlineCertificate": "{{sciezka-do-certyfikatu-offline}}",
    "offlineCertificatePassword": "{{haslo}}"
  },
  "isActive": true
}

Ważne: Wszystkie cztery pola certyfikatu są wymagane. Certyfikat online jest potrzebny do uwierzytelniania podczas trybu online. Certyfikat offline jest potrzebny do generowania kodów QR w PDF, zarówno podczas przetwarzania online, jak i offline.

Przy kodzie statusu 410 PSB automatycznie uruchamia tryb offline. Faktura jest wtedy przetwarzana lokalnie z certyfikatem offline i wysyłana, gdy KSeF będzie ponownie dostępny. Przy 429 PSB planuje automatyczne ponowienie.

KSeF ma codzienny okres przerwy, podczas którego system nie jest dostępny do rejestracji w trybie batch. Po około godzinie 23:00 czasu polskiego tryb offline uruchamia się, gdy tylko KSeF jest nieosiągalny (kod statusu 410):

• Online: faktura jest bezpośrednio rejestrowana w KSeF, pobierane jest UPO i generowany jest PDF z kodami QR
• Offline: faktura jest przetwarzana lokalnie, generowany jest offline PDF z kodem QR offline za pomocą certyfikatu offline. Faktura jest wysyłana do odbiorcy bez wcześniejszej rejestracji w KSeF.

Po powrocie KSeF faktury przetworzone offline są dodatkowo rejestrowane, a faktura otrzymuje kod statusu 201 (InvoiceCleared). Faktura nie jest wtedy ponownie wysyłana do odbiorcy; wcześniej wysłany kod QR offline po tej późniejszej rejestracji wskazuje na potwierdzoną rejestrację KSeF.

Po rejestracji online (clearance) KSeF zwraca numer referencyjny. Numer ten znajduje się w UPO oraz w szczegółach wychodzącego webhooka, na przykład:

"details": {
  "clearanceReference": "234563218-20260220-50683A000001-11",
  "clearanceSystem": "KSeF"
}

Proszę zachować numer referencyjny w wysyłającym systemie ERP jako dowód rejestracji w KSeF.

Przy dużych wolumenach: proszę umieścić hook wsadowy przed hookiem KSeF, tak aby faktury trafiały okresowo (na przykład co 15 sekund do 1 minuty, lub maksymalnie 100 sztuk naraz) jako paczka do KSeF. Dzięki temu integracja rzadziej osiąga limity szybkości KSeF. Preferowany wzorzec tematów: ClearInvoice → batch → ClearInvoiceBatched → hook KSeF. Dodatkowo potrzebny jest osobny hook publikujący faktury wychodzące na temat ClearInvoice (zależnie od przepływu).

Przykładowy hook wsadowy (preferowany; parametry do dostosowania per klient):

{
  "id": "batchClearInvoice",
  "name": "Batch Invoices for KSeF",
  "action": "batch://zip?period=00:01:00&maxBatchSize=100&excludePrimaryAttachment=false&includeAdditionalAttachments=true&hashAlgorithm=sha256&includeRefToMetaAttributes=true&targetDocumentTypeId=econnect-docid%3A%3Ahttp%3A%2F%2Fcrd.gov.pl%2Fwzor%2F2025%2F06%2F25%2F13775%3A%3AFaktura%23%23ksef%3A%3A3.0",
  "topics": ["ClearInvoice"],
  "isActive": true
}

Krótka forma akcji (ten sam cel FA(3); period na przykład 00:00:15):

batch://zip?period=00:00:15&maxBatchSize=100&excludePrimaryAttachment=false&includeAdditionalAttachments=true&hashAlgorithm=sha256&includeRefToMetaAttributes=true&targetDocumentTypeId=econnect-docid%3A%3Ahttp%3A%2F%2Fcrd.gov.pl%2Fwzor%2F2025%2F06%2F25%2F13775%3A%3AFaktura%23%23ksef%3A%3A3.0

Niektórzy klienci nie mogą wysyłać faktur z tematem ClearInvoice (na przykład Business Central). W takim przypadku proszę dostosować hook wsadowy, aby nasłuchiwał na SendInvoice i nadal publikował ClearInvoiceBatched:

{
  "id": "batchClearInvoice",
  "name": "Batch Invoices for KSeF",
  "action": "batch://zip?period=00:01:00&maxBatchSize=100&excludePrimaryAttachment=false&includeAdditionalAttachments=true&hashAlgorithm=sha256&includeRefToMetaAttributes=true&targetDocumentTypeId=econnect-docid%3A%3Ahttp%3A%2F%2Fcrd.gov.pl%2Fwzor%2F2025%2F06%2F25%2F13775%3A%3AFaktura%23%23ksef%3A%3A3.0",
  "topics": ["SendInvoice"],
  "output": [
    { "when": "200", "topic": "ClearInvoiceBatched" },
    { "when": "500", "topic": "ClearInvoiceBatchedError" },
    { "when": "429", "topic": "ClearInvoiceBatchedRetry" }
  ],
  "isActive": true
}

Hook inbound KSeF przetwarza faktury przychodzące dla strony kupującej (Podmiot2). Hook okresowo odpytuje KSeF o nowe faktury, pobiera XML faktury po numerze KSeF i dostarcza go przez platformę PSB.

Uwierzytelnianie wobec KSeF odbywa się wyłącznie za pomocą certyfikatu online (.key + .crt + hasło). Przepływ inbound nie ma wariantu offline, w przeciwieństwie do hooka outbound. W przypadku tymczasowej niedostępności KSeF odpytywanie jest ponawiane zgodnie ze skonfigurowaną polityką retry.

Jeśli podczas Fetch nie znaleziono żadnej faktury, hook przechodzi bezpośrednio do Complete: nic nie jest przetwarzane ani publikowane.

• Ważny certyfikat online dla KSeF (.key + .crt) wraz z odpowiednim hasłem.
• Hook musi być aktywowany w konfiguracji.
• Pola init onlineCertificate i onlineCertificatePassword są wymagane (brak pól certyfikatu offline).

Hook inbound jest konfigurowany przez TechSupport: obsługa certyfikatów jest procedurą dostępną wyłącznie dla wsparcia technicznego, a nie w trybie samoobsługowym.

Parametr action określa okno czasowe, w które hook zagląda wstecz: ksef:inbound?lookbackWindow=<okno>. W init znajduje się wyłącznie certyfikat online.

Standardowo (publikuje na temacie ReceiveInvoice):

{
  "id": "ksef-inbound",
  "action": "ksef:inbound?lookbackWindow=08:00:00",
  "name": "KSeF Hook Inbound",
  "publishTopics": ["ReceiveInvoice"],
  "init": {
    "onlineCertificate": "{{sciezka-do-certyfikatu-online}}",
    "onlineCertificatePassword": "{{haslo}}"
  },
  "isActive": true
}

Po hooku inbound zawsze powinien następować hook uzupełniający, który dalej przetwarza otrzymaną fakturę.

Wariant platformy Collabrr: na platformie Collabrr hook nasłuchuje w tenancie z publishTopics: ["InvoiceReceived"]. Organizacja musi być zarejestrowana do odbioru Peppol na platformie. Przykładowa akcja: ksef:inbound?lookbackWindow=08.00:00:00.

Parametr lookbackWindow określa okno czasowe, w które hook zagląda wstecz podczas odpytywania/tworzenia:

• W godzinach, na przykład "08:00:00"
• W dniach, na przykład "60.00:00:00"

KSeF ogranicza spoglądanie wstecz do maksymalnie 3 miesięcy. Przekroczenie tego limitu skutkuje błędem:

21405: Błąd walidacji danych wejściowych. - 'dateRange' must not exceed 3 months.

Ponadto obowiązuje limit szybkości żądań wobec KSeF. Proszę wziąć to pod uwagę przy aktywacji wielu podmiotów z (dużym) lookbackWindow.

Chcą Państwo dowiedzieć się więcej o e-fakturowaniu w Polsce? Proszę przeczytać stronę krajową o polskim obowiązku KSeF.