PSB má dva hooky KSeF: outbound hook pro odchozí faktury (prodávající strana / Podmiot1) a inbound hook pro příchozí faktury (kupující strana / Podmiot2). Oba automatizují výměnu s Krajowým Systemem e-Faktur (KSeF), polským národním systémem elektronické fakturace. Outbound hook je popsán níže jako první; inbound hook je uveden na konci této stránky.

Outbound hook KSeF automatizuje registraci odchozích faktur v KSeF. Faktury se transformují z formátu Peppol BIS Billing 3.0 / UBL (interně také BisV3) do polského formátu FA(3) a registrují jako dávka (batch). Zákazník může FA(3) dodat i sám, pak se krok transformace přeskočí. Po úspěšném zpracování hook vrátí UPO (Urzędowe Poswiadczenie Odbioru, oficiální potvrzení o přijetí) a PDF důkaz přes platformu PSB.

Pro testování a akceptaci nabízí polská státní správa vedle produkčního prostředí ještě dvě další:

Hook podporuje online tok (přímá registrace) i offline tok (když KSeF je dočasně nedostupný, například během denního výpadku). V offline toku se vygeneruje offline PDF na základě offline certifikátu.

• Platný online certifikát pro KSeF (.key + .crt; autentizace během online toku)
• Platný offline certifikát pro KSeF (.key + .crt; QR kódy ve výstupním PDF, jak při online, tak při offline zpracování)
• Příslušná hesla obou certifikátů
• Hook musí být aktivován v konfiguraci

Po přijetí upozornění na fakturu hook projde sedmi kroky:

Když KSeF není dostupný (denní výpadek nebo porucha), offline tok se spustí automaticky: vygeneruje se offline PDF přes offline certifikát, poté se faktura odešle běžným kanálem.

Zaregistrujte hook přes 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šechna čtyři pole certifikátu jsou povinná. Online certifikát je potřebný pro autentizaci během online toku. Offline certifikát je potřebný pro generování QR kódů v PDF, při online i offline zpracování.

Při stavovém kódu 410 PSB automaticky spustí offline tok. Faktura se pak zpracuje lokálně s offline certifikátem a odešle se, jakmile bude KSeF opět dostupný. Při 429 PSB naplánuje automatické opakování.

KSeF má denní odstávku, během které systém není dostupný pro dávkovou registraci. Přibližně po 23:00 polského místního času se spustí offline tok, jakmile je KSeF nedosažitelný (stavový kód 410):

• Online: faktura se přímo zaregistruje v KSeF, stáhne se UPO a vygeneruje se PDF s QR kódy
• Offline: faktura se zpracuje lokálně, vygeneruje se offline PDF s offline QR kódem přes offline certifikát. Faktura se odešle příjemci, aniž by již byla zaregistrována u KSeF.

Po návratu KSeF se offline zpracované faktury dodatečně zaregistrují a faktura obdrží stavový kód 201 (InvoiceCleared). Faktura se pak znovu neposílá příjemci; dříve odeslaný offline QR kód po této pozdější registraci odkazuje na potvrzenou registraci KSeF.

Po online clearance vrátí KSeF referenční číslo. Toto číslo je uvedeno v UPO a v podrobnostech odchozího webhooku, například:

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

Uchovejte referenční číslo v odesílajícím ERP jako doklad o registraci u KSeF.

Při vysokých objemech: umístěte dávkový hook před hook KSeF, aby faktury odcházely do KSeF periodicky (například každých 15 sekund až 1 minutu, nebo maximálně 100 kusů najednou) jako dávka. Integrace tak méně často naráží na rate limity KSeF. Preferovaný vzor témat: ClearInvoice → dávka → ClearInvoiceBatched → hook KSeF. Navíc je potřeba samostatný hook, který publikuje odchozí faktury na téma ClearInvoice (v závislosti na toku).

Příklad dávkového hooku (preferovaný; parametry upravit dle 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átká forma akce (stejný cíl FA(3); period napří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

Někteří zákazníci nemohou odesílat faktury s tématem ClearInvoice (například Business Central). V takovém případě upravte dávkový hook tak, aby naslouchal na SendInvoice a přesto 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 zpracovává příchozí faktury pro kupující stranu (Podmiot2). Hook periodicky dotazuje KSeF na nové faktury, získává XML faktury podle čísla KSeF a doručuje jej přes platformu PSB.

Autentizace vůči KSeF probíhá výhradně přes online certifikát (.key + .crt + heslo). Inbound tok nemá offline variantu, na rozdíl od outbound hooku. Při dočasné nedostupnosti KSeF se dotazování opakuje podle nakonfigurované retry-politiky.

Pokud během Fetch není nalezena žádná faktura, hook přeskočí přímo na Complete: nic se nezpracuje ani nepublikuje.

• Platný online certifikát pro KSeF (.key + .crt) plus odpovídající heslo.
• Hook musí být aktivován v konfiguraci.
• Init pole onlineCertificate a onlineCertificatePassword jsou povinná (žádná pole offline certifikátu).

Inbound hook se nastavuje přes TechSupport: zpracování certifikátů je postup výhradně pro technickou podporu, není self-service.

Parametr action určuje časové okno, do kterého se hook dívá zpět: ksef:inbound?lookbackWindow=<okno>. V init je uveden pouze online certifikát.

Standardní (publikuje na téma 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 následovat navazující hook, který přijatou fakturu dále zpracuje.

Varianta platformy Collabrr: na platformě Collabrr hook naslouchá v tenantu s publishTopics: ["InvoiceReceived"]. Organizace musí být na platformě registrována pro příjem Peppol. Příklad akce: ksef:inbound?lookbackWindow=08.00:00:00.

Parametr lookbackWindow určuje časové okno, do kterého se hook dívá zpět při dotazování/vytváření:

• V hodinách, například "08:00:00"
• Ve dnech, například "60.00:00:00"

KSeF omezuje zpětné hledání na maximálně 3 měsíce. Při překročení dojde k chybě:

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

Navíc platí limit rychlosti požadavků vůči KSeF. Vezměte to v úvahu při aktivaci více subjektů s (velkým) lookbackWindow.

Chcete se dozvědět více o elektronické fakturaci v Polsku? Přečtěte si stránku země o polské povinnosti KSeF.