Gestionar la facturación electrónica KSeF en B2Brouter
KSeF (Krajowy System e-Faktur, «Sistema Nacional de Facturas electrónicas») es la plataforma obligatoria del Ministerio de Finanzas de Polonia para la facturación electrónica B2B. Las empresas polacas sujetas a IVA deben enviar cada factura en formato FA(3) a KSeF y recibir un identificador oficial (Numer KSeF) antes de distribuirla al cliente.
B2Brouter se encarga del ciclo completo: firma con el certificado fiscal, transformación a FA(3), envío, recepción del número KSeF y generación del QR y del recibo oficial (UPO).
Para quién — Empresas con NIP polaco (Numer Identyfikacji Podatkowej). Las empresas no polacas no pueden activar KSeF ni seleccionarlo como transporte en un contacto polaco — la factura no se enviaría.
Entornos de KSeF — El Ministerio publica tres: Producción, Demo (mismos datos reales pero sin efectos fiscales) y Test (sandbox abierto para integraciones). La instancia de producción de B2Brouter habla con KSeF Producción; la de staging habla con KSeF Test o Demo según la configuración del certificado.
Producción — Acceded al portal web oficial de KSeF del Ministerio de Finanzas polaco en ap.ksef.mf.gov.pl/web identificándoos con vuestro sistema de identidad fiscal (Profil Zaufany, firma cualificada o similar). Dentro del portal, en la sección de certificados/credenciales, generad un certificado de autenticación ligado a vuestro NIP y exportadlo en formato PKCS#12 (.p12 o .pfx) con una contraseña. El fichero que obtendréis tiene un nombre similar a <NIP>_Uwierzytelnianie.pfx (Uwierzytelnianie = Autenticación).
Test (pruebas e integraciones) — El portal web equivalente de pruebas es ap-test.ksef.mf.gov.pl/web. Podéis generar un certificado autofirmado con OpenSSL; el subject debe incluir el NIP en el campo serialNumber=TINPL-<NIP>. Antes de usarlo, registradlo manualmente en ese mismo portal: sin este paso, KSeF Test rechazará todas las firmas de ese certificado por desconocido.
Solo sirve PKCS#12 (.p12 / .pfx) — Un fichero .crtno sirve: solo contiene la parte pública, no la clave privada, y KSeF necesita ambas para autenticar la firma. Si el portal os da otra cosa, volved a exportarlo escogiendo explícitamente PKCS#12 y marcando «incluye la clave privada». Solo como último recurso, si disponéis del .crt y la .key por separado, podéis combinarlos con OpenSSL:
openssl pkcs12 -export \
-in ksef_certificate.crt \
-inkey ksef_private_key.key \
-out ksef_certificate.p12 \
-name "<NOMBRE_EMPRESA> <NIP>" \
-passout pass:<CONTRASEÑA>
Algoritmo de cifrado — 3DES o AES — Si recibís el error «Certificate password is invalid» a pesar de introducir la contraseña correcta, el fichero está cifrado con un algoritmo antiguo (RC2-40bit, típico de exportaciones hechas desde Windows antiguo). KSeF y B2Brouter solo aceptan 3DES o AES. Volved a exportar con OpenSSL:
Entorno — Producción por defecto. Demo o Test solo si estáis en pruebas.
Guardar.
Cuando guardéis, B2Brouter conecta con KSeF, valida el certificado y comprueba que el NIP del subject coincide con el NIP de la cuenta (o que la empresa esté autorizada vía ZAW-FA). Si la validación es correcta, el certificado queda guardado y KSeF queda activo para vuestra cuenta.
Una vez KSeF está activo, el tax report se genera solo — No tenéis que hacer nada más. Cada factura emitida a un contacto polaco vía KSeF generará automáticamente su tax report y se enviará a KSeF como parte del mismo flujo de emisión. Si integráis vía API, configurad el tax_report_setting con auto_generate: true y auto_send: true para que el flujo sea equivalente al de la UI.
Si el subject del certificado no coincide con el NIP de la cuenta — Debéis presentar el formulario ZAW-FA en el portal oficial para autorizar a vuestra empresa a emitir facturas con este certificado. Hasta que ZAW-FA esté aprobado, KSeF rechazará las facturas con error 450 o similar.
Antes de emitir una factura a un cliente, este debe existir en los contactos.
Contactos → Nuevo contacto.
Seleccionad el país del cliente.
Introducid el identificador fiscal — depende del país del cliente (ver tabla abajo).
Validar identificador y continuar — para clientes polacos, B2Brouter conecta con el registro del Ministerio para verificar el NIP y autocompletar la razón social.
Rellenad la dirección (calle, código postal, ciudad).
Configurad el método de entrega y elegid KSeF como transporte. Si no aparece la opción KSeF, cambiad el tipo de red a la que muestre KSeF en la lista (en algunas cuentas es una red abierta que agrupa varios transportes).
Guardar.
Tres estructuras de identificación según el país del cliente
KSeF exige informar al cliente en una de tres estructuras mutuamente excluyentes. Si mezcláis formatos (NIP con prefijo, prefijo sin país, etc.) en la misma cuenta, obtendréis errores intermitentes — unas facturas pasan y otras son rechazadas.
Tipo de cliente
Identificador a introducir
Cómo lo genera KSeF en el XML
Polaco
NIP (exactamente 10 cifras, sin prefijo PL)
Podmiot2/DaneIdentyfikacyjne/NIP
Otro país UE
Número de IVA sin prefijo de país (p. ej. 123456789 para DE123456789)
No mezcléis formatos — Para un mismo cliente, enviad siempre el mismo tipo de identificador. Si en una factura lo enviáis como polaco (PL + NIP) y en la siguiente como UE (DE + VAT), KSeF aplicará reglas de validación distintas y el resultado será inconsistente.
Grecia: código fiscal EL, no GR — En el campo fiscal UE (en KSeF, KodUE), Grecia se identifica con EL. En la dirección sí se usa GR. Si el formulario os deja elegir GR en el campo fiscal, corregidlo a EL; si no, KSeF rechazará la factura con el error KodUE: 'GR' is not an element of the set {...}.
Divisa — PLN para facturas domésticas. Para divisas extranjeras, rellenad el tipo de cambio a PLN en la fecha de factura: se enviará al campo KSeF KursWalutyZ.
Notas — texto libre que aparecerá como pie de factura (Stopka) en el PDF oficial. Útil para cláusulas legales, condiciones contractuales o cualquier información que no encaje en ningún otro campo.
Operación exenta (uso de exención de la Ley de IVA)
Inversión sujeto pasivo doméstica
oo
Odwrotne obciążenie — reverse charge PL
No sujeto UE
np I
Servicios transfronterizos no sujetos (Art. 28b)
Líneas exentas (zw) — fundamento legal en el Comentario — Para líneas con tipo exento, indicad el fundamento legal (p. ej. «art. 43 ust. 1 pkt 37 ustawy VAT») en el campo Comentario de la línea. En el PDF aparecerán dos párrafos: una anotación legal genérica (automática) y el comentario que hayáis escrito.
Para una exportación fuera de la UE con divisa extranjera:
Tipo de IVA: 0 EX.
País del comprador: el país no UE.
Tipo de cambio: el del día anterior a la fecha de IVA, según la tabla del BCE o NBP.
No uséis zw (exento) para exportaciones — Una exportación es 0 EX (zero-rate por exportación, P_13_6_3). Si usáis zw, el importe queda duplicado entre las casillas domésticas zero-rate y exención, y KSeF rechaza o distorsiona la declaración.
En la ficha de una factura emitida veréis el estado actual, el Numer KSeF una vez registrada, y el recibo UPO.
Sending → Registered → (QR + Numer KSeF + UPO)
↘ Error
Sending — B2Brouter ha firmado y enviado el documento. El registro efectivo en KSeF puede tardar unos minutos, especialmente en horas punta o al cierre de mes.
Registered ✅ — KSeF ha validado y asignado el Numer KSeF (NrKSeF). El QR de la factura impresa pasa a mostrar este número y queda disponible el justificante oficial de registro (ver abajo).
Error ❌ — KSeF ha rechazado el documento. El motivo aparece en la ficha (código + descripción en polaco).
El QR aparece enseguida, pero eso no significa que KSeF haya aceptado la factura — B2Brouter genera el código QR localmente a partir del hash criptográfico, el NIP y la fecha: es visible inmediatamente, incluso si la factura acabará en error. El único indicador fiable de aceptación es el estado Registered. Si el estado es Error, la factura no está registrada en KSeF independientemente del QR o el enlace generados. Mientras la factura esté Sending, el QR lleva la etiqueta OFFLINE.
Qué es. El UPO (Urzędowe Poświadczenie Odbioru, en castellano Acuse Oficial de Recepción) es el justificante que emite KSeF cuando acepta y registra la factura. Funciona como un acuse administrativo: es la prueba legal, con valor fiscal, de que habéis cumplido la obligación de registrar la factura en KSeF en un momento concreto.
Técnicamente es un documento XML firmado digitalmente por el Ministerio de Finanzas polaco. Contiene el Numer KSeF (NrKSeF) asignado a la factura, la marca de tiempo exacta del registro y la firma del Ministerio. No es un PDF visual — es una prueba legal legible por máquina.
De dónde sale. Lo genera KSeF en el momento de validar y aceptar la factura. No lo genera B2Brouter ni vosotros.
Cómo confirmar el registro desde B2Brouter. Cuando la factura pasa a Registered, abrid el tax report KSeF asociado (enlazado desde la ficha de la factura). En la pestaña Actividad veréis el evento de envío correcto con el Numer KSeF asignado — confirmación de que KSeF ha recibido, validado y registrado el documento.
Cómo obtener el fichero XML del UPO para vuestro archivo contable. El fichero original queda disponible por dos vías:
Desde el portal oficial de KSeF — ap.ksef.mf.gov.pl/web (o ap-test.ksef.mf.gov.pl/web para el entorno de pruebas). Accediendo con vuestro sistema de identidad fiscal, podéis consultar y descargar los UPOs de vuestra cuenta directamente del Ministerio — son el original oficial.
Vía API de B2Brouter — si integráis con la API, el UPO está disponible como adjunto del tax report. Ver la Guía KSeF para desarrolladores.
Conservad los UPO con la factura — Tienen valor jurídico ante una inspección fiscal. Descargadlos de KSeF o vía API y archivadlos junto con la factura original.
Abrid la factura y leed el código y descripción del error.
Corregid los datos problemáticos (contacto, NIP, importes…).
Volved a enviar la factura. B2Brouter reintenta el registro en KSeF con los datos corregidos.
Excepción — número de factura ya visto por KSeF — Si el rechazo viene del hecho de que el número de factura ya se ha utilizado en un envío anterior, no podréis reenviar el mismo documento: eliminadlo, corregid los datos y cread una factura nueva con número distinto.
Una factura rectificativa (faktura korygująca) modifica una factura KSeF anterior. El documento enlaza la original (DaneFaKorygowanej) y reexpresa las líneas afectadas con indicación del estado anterior y nuevo.
Crear factura rectificativa — B2Brouter rellena automáticamente el número KSeF, el número de factura y la fecha de la original.
Indicad el Tipo de efecto (TypKorekty):
1 — Efecto en la fecha de la factura original. Uso: correcciones de errores existentes al emitir (importe mal calculado, tipo de IVA erróneo).
2 — Efecto en la fecha de la factura rectificativa. Uso: hechos posteriores (devoluciones, descuentos post-venta).
3 — Efecto en una fecha diferente — indicadla explícitamente.
Actualizad las líneas al nuevo estado (cantidades, precios, tipos de IVA).
Si queréis añadir un motivo textual de la corrección (p. ej. «Korekta ilości — dostawa niepełna») o cualquier texto legal asociado, escribidlo en el campo Notas de la factura: se envía al pie oficial del documento (Stopka/Informacje/StopkaFaktury) y es visible en el PDF de KSeF.
Emitir y enviar.
Estado «antes / después» — La rectificativa que emitís desde el formulario lleva directamente las líneas con los valores nuevos; este es el caso habitual y suficiente para la mayoría de correcciones. Si necesitáis la representación formal antes/después (líneas originales anuladas más las nuevas en el mismo documento, con marcador Stan przed por línea), esta opción solo es accesible vía API: ved la Guía para desarrolladores.
Para rectificar una ZAL (anticipo), usad una KOR_ZAL; para rectificar una ROZ (liquidación), usad una KOR_ROZ. El procedimiento es idéntico al de una KOR normal.
Una vez KSeF está activado en la cuenta, vuestro NIP queda registrado como receptor y los proveedores polacos pueden enviaros facturas directamente.
Gastos → aquí encontraréis todas las facturas KSeF recibidas.
Abrid una factura para ver su detalle.
Dónde está el Numer KSeF de una factura recibida — El número KSeF oficial (NrKSeF) no aparece sobre la imagen del PDF preview, sino en la sección Actividad de la factura recibida (formato XXXXXXXXXX-AAAAMMDD-XXXXXXXXXXXX-XX). El QR solo es visible en el PDF si el proveedor lo ha incluido en su imagen.
Una factura que el proveedor dice haber emitido pero no aparece en Gastos — Primero verificad que el PDF que os ha enviado el proveedor lleva código QR de KSeF. Sin QR, la factura no se ha enviado vía KSeF — el proveedor quizás no ha completado el registro. Si hay QR, escaneadlo y copiad su URL: con esa URL podemos comprobar si el documento existe realmente en KSeF.
Nueva — recibida en B2Brouter, pendiente de vuestra revisión.
Leída — la habéis abierto al menos una vez.
Aprobada / Rechazada — el estado que le habéis asignado (no se envía ningún mensaje al proveedor; KSeF no tiene un canal de aceptación/rechazo equivalente al de Peppol).
Certificado rechazado a pesar de la contraseña correcta — el PKCS#12 está cifrado con un algoritmo antiguo (RC2-40bit), típico de exportaciones hechas desde Windows antiguo. Volved a exportar con 3DES o AES (ver § 1).
450 - Nip nabywcy: '…' jest nieprawidłowy — NIP del comprador inválido. Comprobad 10 cifras + dígito de control. Para contactos UE, usad el número de IVA UE sin prefijo (ver § 2).
KodUE: 'GR' is not an element of the set — Grecia en el campo fiscal UE debe ir como EL, no GR. Editad el contacto y corregidlo.
«Contact Email can’t be blank» — el transporte del contacto es email pero no hay dirección. Añadid un email o cambiad el transporte.
Estado Error pero se ha generado QR y URL — normal. El QR se calcula en local y no depende de la aceptación de KSeF. El estado Error es autoritativo: la factura no está registrada.
Factura que el proveedor dice haber emitido pero no aparece en Gastos — comprobad que el PDF del proveedor lleva código QR de KSeF. Sin QR, no se ha registrado realmente.
Resumen de IVA muestra «23% lub 22%» — etiqueta oficial del template del Ministerio, que combina el tipo histórico (22 %) y el actual (23 %) en un único campo. No es un error.
Campo «Nazwa banku» (nombre del banco) vacío — KSeF no exige el nombre del banco y B2Brouter no lo rellena automáticamente. Si lo necesitáis, añadidlo al campo Notas.
Este manual describe la UI. Si integráis con B2Brouter vía API, la referencia oficial es la Guía KSeF para desarrolladores — cubre los endpoints Tax Report Settings, Tax Reports, Invoices y Contacts, el mapeo completo entre JSON y FA(3), los webhooks de seguimiento de estados y la descarga del UPO.
Autenticación mediante API key estática (cabecera X-B2B-API-Key) + versión de API (X-B2B-API-Version). Las funcionalidades específicas de KSeF requieren versión 2025-10-13 o posterior.
