PSB má dva hooky KSeF: outbound hook pre odchádzajúce faktúry (predávajúca strana / Podmiot1) a inbound hook pre prichádzajúce faktúry (kupujúca strana / Podmiot2). Oba automatizujú výmenu s Krajowym Systeme e-Faktur (KSeF), poľským národným systémom elektronickej fakturácie. Outbound hook je opísaný nižšie ako prvý; inbound hook sa nachádza na konci tejto stránky.

Outbound hook KSeF automatizuje registráciu odchádzajúcich faktúr v KSeF. Faktúry sa transformujú z formátu Peppol BIS Billing 3.0 / UBL (interne aj BisV3) do poľského formátu FA(3) a registrujú ako dávka (batch). Zákazník môže FA(3) dodať aj sám, vtedy sa krok transformácie preskočí. Po úspešnom spracovaní hook vráti UPO (Urzędowe Poswiadczenie Odbioru, oficiálne potvrdenie o prijatí) a PDF dôkaz cez platformu PSB.

Na testovanie a akceptáciu ponúka poľská štátna správa okrem produkčného prostredia ešte dve ďalšie:

Hook podporuje online tok (priama registrácia) aj offline tok (keď KSeF je dočasne nedostupný, napríklad počas denného výpadku). V offline toku sa vygeneruje offline PDF na základe offline certifikátu.

• Platný online certifikát pre KSeF (.key + .crt; autentifikácia počas online toku)
• Platný offline certifikát pre KSeF (.key + .crt; QR kódy vo výstupnom PDF, pri online aj offline spracovaní)
• Príslušné heslá oboch certifikátov
• Hook musí byť aktivovaný v konfigurácii

Po prijatí upozornenia na faktúru hook prejde siedmimi krokmi:

Keď KSeF nie je dostupný (denný výpadok alebo porucha), offline tok sa spustí automaticky: vygeneruje sa offline PDF cez offline certifikát, potom sa faktúra odošle bežným kanálom.

Zaregistrujte hook cez API Hooks:

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

Dôležité: Všetky štyri polia certifikátu sú povinné. Online certifikát je potrebný na autentifikáciu počas online toku. Offline certifikát je potrebný na generovanie QR kódov v PDF, pri online aj offline spracovaní.

Pri stavovom kóde 410 PSB automaticky spustí offline tok. Faktúra sa potom spracuje lokálne s offline certifikátom a odošle sa, keď bude KSeF opäť dostupný. Pri 429 PSB naplánuje automatické opakovanie.

KSeF má dennú odstávku, počas ktorej systém nie je dostupný na dávkovú registráciu. Približne po 23:00 poľského miestneho času sa spustí offline tok, hneď ako je KSeF nedosiahnuteľný (stavový kód 410):

• Online: faktúra sa priamo zaregistruje v KSeF, stiahne sa UPO a vygeneruje sa PDF s QR kódmi
• Offline: faktúra sa spracuje lokálne, vygeneruje sa offline PDF s offline QR kódom cez offline certifikát. Faktúra sa odošle príjemcovi bez toho, aby už bola zaregistrovaná v KSeF.

Po návrate KSeF sa offline spracované faktúry dodatočne zaregistrujú a faktúra dostane stavový kód 201 (InvoiceCleared). Faktúra sa potom znova neposiela príjemcovi; predtým odoslaný offline QR kód po tejto neskoršej registrácii odkazuje na potvrdenú registráciu KSeF.

Po online clearance vráti KSeF referenčné číslo. Toto číslo je uvedené v UPO a v podrobnostiach odchádzajúceho webhooku, napríklad:

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

Uchovajte referenčné číslo v odosielajúcom ERP ako doklad o registrácii v KSeF.

Pri veľkých objemoch: umiestnite dávkový hook pred hook KSeF, aby faktúry odchádzali do KSeF periodicky (napríklad každých 15 sekúnd až 1 minútu, alebo maximálne 100 kusov naraz) ako dávka. Integrácia tak menej často naráža na rate limity KSeF. Preferovaný vzor tém: ClearInvoice → dávka → ClearInvoiceBatched → hook KSeF. Navyše je potrebný samostatný hook, ktorý publikuje odchádzajúce faktúry na tému ClearInvoice (v závislosti od toku).

Príklad dávkového hooku (preferovaný; parametre upraviť podľa zákazníka):

{
  "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 akcie (rovnaký cieľ FA(3); period napríklad 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

Niektorí zákazníci nemôžu odosielať faktúry s témou ClearInvoice (napríklad Business Central). V takom prípade upravte dávkový hook tak, aby počúval na SendInvoice a napriek tomu publikoval 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
}

Inbound hook KSeF spracováva prichádzajúce faktúry pre kupujúcu stranu (Podmiot2). Hook periodicky dopytuje KSeF na nové faktúry, získava XML faktúry podľa čísla KSeF a doručuje ho cez platformu PSB.

Autentifikácia voči KSeF prebieha výhradne cez online certifikát (.key + .crt + heslo). Inbound tok nemá offline variantu, na rozdiel od outbound hooku. Pri dočasnej nedostupnosti KSeF sa dopytovanie opakuje podľa nakonfigurovanej retry politiky.

Ak sa počas Fetch nenájde žiadna faktúra, hook preskočí priamo na Complete: nič sa nespracuje ani nepublikuje.

• Platný online certifikát pre KSeF (.key + .crt) plus zodpovedajúce heslo.
• Hook musí byť aktivovaný v konfigurácii.
• Init polia onlineCertificate a onlineCertificatePassword sú povinné (žiadne polia offline certifikátu).

Inbound hook sa nastavuje cez TechSupport: spracovanie certifikátov je postup výhradne pre technickú podporu, nie je to self-service.

Parameter action určuje časové okno, do ktorého sa hook pozerá späť: ksef:inbound?lookbackWindow=<okno>. V init je uvedený iba online certifikát.

Štandardná (publikuje na tému ReceiveInvoice):

{
  "id": "ksef-inbound",
  "action": "ksef:inbound?lookbackWindow=08:00:00",
  "name": "KSeF Hook Inbound",
  "publishTopics": ["ReceiveInvoice"],
  "init": {
    "onlineCertificate": "{{cesta-k-online-certifikatu}}",
    "onlineCertificatePassword": "{{heslo}}"
  },
  "isActive": true
}

Po inbound hooku musí vždy nasledovať nadväzujúci hook, ktorý prijatú faktúru ďalej spracuje.

Variant platformy Collabrr: na platforme Collabrr hook počúva v tenante s publishTopics: ["InvoiceReceived"]. Organizácia musí byť na platforme registrovaná na príjem Peppol. Príklad akcie: ksef:inbound?lookbackWindow=08.00:00:00.

Parameter lookbackWindow určuje časové okno, do ktorého sa hook pozerá späť pri dopytovaní/vytváraní:

• V hodinách, napríklad "08:00:00"
• V dňoch, napríklad "60.00:00:00"

KSeF obmedzuje spätné hľadanie na maximálne 3 mesiace. Pri prekročení dôjde k chybe:

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

Okrem toho platí limit rýchlosti požiadaviek voči KSeF. Zohľadnite to pri aktivácii viacerých subjektov s (veľkým) lookbackWindow.

Chcete sa dozvedieť viac o elektronickej fakturácii v Poľsku? Prečítajte si stránku krajiny o poľskej povinnosti KSeF.