La PSB dispone de dos hooks KSeF: un hook outbound para facturas salientes (parte vendedora / Podmiot1) y un hook inbound para facturas entrantes (parte compradora / Podmiot2). Ambos automatizan el intercambio con el Krajowy System e-Faktur (KSeF), el sistema nacional de facturación electrónica polaco. El hook outbound se describe primero a continuación; el hook inbound se encuentra al final de esta página.

El hook outbound KSeF automatiza el registro de facturas salientes en KSeF. Las facturas se transforman de Peppol BIS Billing 3.0 / UBL (internamente también BisV3) al formato polaco FA(3) y se registran como lote. El cliente también puede suministrar FA(3) directamente, en cuyo caso se omite el paso de transformación. Tras el procesamiento correcto, el hook devuelve el UPO (Urzędowe Poswiadczenie Odbioru, el acuse de recibo oficial) y una prueba en PDF a través de la plataforma PSB.

Para pruebas y aceptación, la administración polaca ofrece dos entornos además de producción:

El hook admite tanto un flujo en línea (registro directo) como un flujo fuera de línea (cuando KSeF no está disponible temporalmente, por ejemplo, durante el corte diario). En el flujo fuera de línea se genera un PDF fuera de línea basado en el certificado fuera de línea.

• Un certificado en línea válido para KSeF (.key + .crt; autenticación durante el flujo en línea)
• Un certificado fuera de línea válido para KSeF (.key + .crt; códigos QR en la salida PDF, tanto en procesamiento en línea como fuera de línea)
• Las contraseñas correspondientes de ambos certificados
• El hook debe estar activado en la configuración

Tras recibir una notificación de factura, el hook pasa por siete pasos:

Cuando KSeF no está disponible (corte diario o avería), el flujo fuera de línea se inicia automáticamente: se genera un PDF fuera de línea mediante el certificado fuera de línea, tras lo cual la factura se envía por el canal regular.

Registre el hook a través de la API de Hooks:

{
  "id": "ksef-sender",
  "action": "ksef",
  "name": "KSeF Hook Sender",
  "topics": [
    "ClearInvoiceBatched"
  ],
  "output": [
    {
      "when": "200",
      "topic": "SendInvoice"
    },
    {
      "when": "410",
      "topic": "SendInvoice"
    }
  ],
  "init": {
    "onlineCertificate": "{{ruta-al-certificado-en-linea}}",
    "onlineCertificatePassword": "{{contraseña}}",
    "offlineCertificate": "{{ruta-al-certificado-fuera-de-linea}}",
    "offlineCertificatePassword": "{{contraseña}}"
  },
  "isActive": true
}

Importante: Los cuatro campos de certificado son obligatorios. El certificado en línea es necesario para la autenticación durante el flujo en línea. El certificado fuera de línea es necesario para la generación de códigos QR en el PDF, tanto en el procesamiento en línea como fuera de línea.

Con el código de estado 410, la PSB inicia automáticamente el flujo fuera de línea. La factura se procesa entonces localmente con el certificado fuera de línea y se envía cuando KSeF vuelve a estar disponible. Con 429, la PSB programa un reintento automático.

KSeF tiene un periodo de corte diario durante el cual el sistema no está disponible para el registro en lotes. A partir de aproximadamente las 23:00 hora local polaca, el flujo fuera de línea se activa en cuanto KSeF no está accesible (código de estado 410):

• En línea: la factura se registra directamente en KSeF, se recupera el UPO y se genera un PDF con códigos QR
• Fuera de línea: la factura se procesa localmente, se genera un PDF fuera de línea con un código QR fuera de línea mediante el certificado fuera de línea. La factura se envía al destinatario sin haber sido aún registrada en KSeF.

Tras el regreso de KSeF, las facturas procesadas fuera de línea se registran a posteriori y la factura recibe el código de estado 201 (InvoiceCleared). La factura no se reenvía al destinatario; el código QR fuera de línea enviado anteriormente apunta, tras este registro posterior, al registro KSeF confirmado.

Tras la clearance en línea, KSeF devuelve un número de referencia. Este número aparece en el UPO y en los detalles del webhook saliente, por ejemplo:

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

Conserve el número de referencia en el ERP emisor como prueba de registro ante KSeF.

Para volúmenes elevados: coloque un hook de lote antes del hook KSeF para que las facturas se envíen periódicamente (por ejemplo, cada 15 segundos hasta 1 minuto, o un máximo de 100 a la vez) como lote a KSeF. Así la integración alcanza con menor frecuencia los límites de velocidad de KSeF. Patrón de topic preferido: ClearInvoice → lote → ClearInvoiceBatched → hook KSeF. Además, se necesita un hook independiente que publique las facturas salientes en el topic ClearInvoice (según el flujo).

Ejemplo de hook de lote (preferido; parámetros a ajustar por cliente):

{
  "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
}

Forma corta de la acción (mismo objetivo FA(3); period por ejemplo 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

Algunos clientes no pueden enviar facturas con el topic ClearInvoice (por ejemplo Business Central). En ese caso, ajuste el hook de lote para que escuche SendInvoice y siga publicando 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
}

El hook inbound KSeF procesa facturas entrantes para la parte compradora (Podmiot2). El hook consulta periódicamente KSeF en busca de nuevas facturas, recupera el XML de la factura por número KSeF y lo entrega a través de la plataforma PSB.

La autenticación frente a KSeF se realiza exclusivamente mediante un certificado en línea (.key + .crt + contraseña). El flujo inbound no tiene variante fuera de línea, a diferencia del hook outbound. En caso de indisponibilidad temporal de KSeF, la consulta se reintenta conforme a la política de reintentos configurada.

Si no se encuentra ninguna factura durante Fetch, el hook salta directamente a Complete: no se procesa ni publica nada.

• Un certificado en línea válido para KSeF (.key + .crt) más la contraseña correspondiente.
• El hook debe estar activado en la configuración.
• Los campos init onlineCertificate y onlineCertificatePassword son obligatorios (sin campos de certificado fuera de línea).

El hook inbound se configura a través de TechSupport: el manejo de certificados es un procedimiento exclusivo de soporte técnico, no de autoservicio.

El parámetro de acción determina la ventana temporal en la que el hook mira hacia atrás: ksef:inbound?lookbackWindow=<ventana>. En init solo figura el certificado en línea.

Estándar (publica en el topic ReceiveInvoice):

{
  "id": "ksef-inbound",
  "action": "ksef:inbound?lookbackWindow=08:00:00",
  "name": "KSeF Hook Inbound",
  "publishTopics": ["ReceiveInvoice"],
  "init": {
    "onlineCertificate": "{{ruta-al-certificado-en-linea}}",
    "onlineCertificatePassword": "{{contraseña}}"
  },
  "isActive": true
}

Tras el hook inbound siempre debe seguir un hook de seguimiento que procese posteriormente la factura recibida.

Variante de plataforma Collabrr: en la plataforma Collabrr, el hook escucha en el tenant con publishTopics: ["InvoiceReceived"]. La organización debe estar registrada para la recepción Peppol en la plataforma. Ejemplo de acción: ksef:inbound?lookbackWindow=08.00:00:00.

El parámetro lookbackWindow determina la ventana temporal en la que el hook mira hacia atrás al consultar/crear:

• En horas, por ejemplo "08:00:00"
• En días, por ejemplo "60.00:00:00"

KSeF limita la mirada hacia atrás a un máximo de 3 meses. Al superarlo, se produce un error:

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

Además, existe un límite de velocidad de solicitudes hacia KSeF. Téngalo en cuenta al activar varias entidades con un lookbackWindow (grande).

¿Desea saber más sobre la facturación electrónica en Polonia? Consulte la página del país sobre la obligación KSeF polaca.