Gestionar la facturació electrònica KSeF a B2Brouter
KSeF (Krajowy System e-Faktur, «Sistema Nacional de Factures electròniques») és la plataforma obligatòria del Ministeri de Finances de Polònia per a la facturació electrònica B2B. Les empreses poloneses subjectes a l’IVA han d’enviar cada factura en format FA(3) a KSeF i rebre’n un identificador oficial (Numer KSeF) abans de distribuir-la al client.
B2Brouter s’encarrega del cicle complet: signatura amb el certificat fiscal, transformació a FA(3), enviament, recepció del número KSeF i generació del QR i del rebut oficial (UPO).
Per a qui — Empreses amb NIP polonès (Numer Identyfikacji Podatkowej). Les empreses no poloneses no poden activar KSeF ni seleccionar-lo com a transport en un contacte polonès — la factura no s’enviaria.
Entorns de KSeF — El Ministeri en publica tres: Producció, Demo (mateixes dades reals però sense efectes fiscals) i Test (sandbox obert per a integracions). La instància de producció de B2Brouter parla amb KSeF Producció; la de staging parla amb KSeF Test o Demo segons la configuració del certificat.
Producció — Accediu al portal web oficial de KSeF del Ministeri de Finances polonès a ap.ksef.mf.gov.pl/web identificant-vos amb el vostre sistema d’identitat fiscal (Profil Zaufany, signatura qualificada o similar). Dins del portal, a la secció de certificats/credencials, genereu un certificat d’autenticació lligat al vostre NIP i exporteu-lo en format PKCS#12 (.p12 o .pfx) amb una contrasenya. El fitxer que obtindreu té un nom similar a <NIP>_Uwierzytelnianie.pfx (Uwierzytelnianie = Autenticació).
Test (proves i integracions) — El portal web equivalent de proves és ap-test.ksef.mf.gov.pl/web. Podeu generar un certificat autosignat amb OpenSSL; el subjecte ha d’incloure el NIP al camp serialNumber=TINPL-<NIP>. Abans d’usar-lo, registreu-lo manualment en aquest mateix portal: fora d’aquest pas, KSeF Test rebutjarà totes les signatures d’aquest certificat per desconegut.
Només serveix PKCS#12 (.p12 / .pfx) — Un fitxer .crtno serveix: només conté la part pública, no la clau privada, i KSeF en necessita les dues per autenticar la signatura. Si el portal us dóna una altra cosa, torneu a fer l’export escollint explícitament PKCS#12 i marcant «inclou la clau privada». Només com a darrer recurs, si disposeu del .crt i de la .key per separat, podeu combinar-los amb OpenSSL:
openssl pkcs12 -export \
-in ksef_certificate.crt \
-inkey ksef_private_key.key \
-out ksef_certificate.p12 \
-name "<NOM_EMPRESA> <NIP>" \
-passout pass:<CONTRASENYA>
Algoritme de xifratge — 3DES o AES — Si rebeu l’error «Certificate password is invalid» tot i introduir la contrasenya correcta, el fitxer està xifrat amb un algoritme antic (RC2-40bit, típic d’exportacions fetes des de Windows antic). KSeF i B2Brouter només accepten 3DES o AES. Re-exporteu amb OpenSSL:
Entorn — Producció per defecte. Demo o Test només si esteu en proves.
Desar.
Quan deseu, B2Brouter connecta amb KSeF, valida el certificat i comprova que el NIP del subjecte coincideix amb el NIP del compte (o que l’empresa hi estigui autoritzada via ZAW-FA). Si la validació és correcta, el certificat queda desat i KSeF queda actiu per al vostre compte.
Un cop KSeF és actiu, el tax report es genera sol — No heu de fer res més. Cada factura emesa a un contacte polonès via KSeF generarà automàticament el seu tax report i s’enviarà a KSeF com a part del mateix flux d’emissió. Si integreu via API, configureu el tax_report_setting amb auto_generate: true i auto_send: true perquè el flux sigui equivalent al de la UI.
Si el subjecte del certificat no coincideix amb el NIP del compte — Heu de presentar el formulari ZAW-FA al portal oficial per autoritzar la vostra empresa a emetre factures amb aquest certificat. Fins que ZAW-FA estigui aprovat, KSeF rebutjarà les factures amb error 450 o similar.
Abans d’emetre una factura a un client, aquest ha d’existir als contactes.
Contactes → Nou contacte.
Seleccioneu el país del client.
Introduïu l’identificador fiscal — depèn del país del client (vegeu la taula de sota).
Validar identificador i continuar — per a clients polonesos, B2Brouter connecta amb el registre del Ministeri per verificar el NIP i autocompletar la raó social.
Empleneu l’adreça (carrer, codi postal, ciutat).
Configureu el mètode de lliurament i trieu KSeF com a transport. Si no us apareix l’opció KSeF, canvieu el tipus de xarxa a la que mostri KSeF a la llista (en alguns comptes és una xarxa oberta que agrupa diversos transports).
Desar.
Tres estructures d’identificació segons el país del client
KSeF exigeix informar el client en una de tres estructures mútuament excloents. Si barregeu formats (NIP amb prefix, prefix sense país, etc.) en el mateix compte, obtindreu errors intermitents — unes factures passen i d’altres són rebutjades.
Tipus de client
Identificador a introduir
Com ho genera KSeF al XML
Polonès
NIP (exactament 10 xifres, sense prefix PL)
Podmiot2/DaneIdentyfikacyjne/NIP
Altre país UE
Número d’IVA sense prefix de país (p. ex. 123456789 per a DE123456789)
No barregeu formats — Per a un mateix client, envieu sempre el mateix tipus d’identificador. Si a una factura l’envieu com a polonès (PL + NIP) i a la següent com a UE (DE + VAT), KSeF aplicarà regles de validació diferents i el resultat serà inconsistent.
Grècia: codi fiscal EL, no GR — Al camp fiscal UE (a KSeF, KodUE), Grècia s’identifica amb EL. A l’adreça sí que s’usa GR. Si el formulari us deixa triar GR al camp fiscal, corregiu-ho a EL; altrament KSeF rebutjarà la factura amb l’error KodUE: 'GR' is not an element of the set {...}.
Divisa — PLN per a factures domèstiques. Per a divises estrangeres, empleneu el tipus de canvi a PLN a la data de factura: s’enviarà al camp KSeF KursWalutyZ.
Notes — text lliure que apareixerà com a peu de factura (Stopka) al PDF oficial. Útil per a clàusules legals, condicions contractuals o qualsevol informació que no encaixi en cap altre camp.
Línies exemptes (zw) — fonament legal al Comentari — Per a línies amb tipus exempt, indiqueu el fonament legal (p. ex. «art. 43 ust. 1 pkt 37 ustawy VAT») al camp Comentari de la línia. Al PDF apareixeran dos paràgrafs: una anotació legal genèrica (automàtica) i el comentari que hàgiu escrit.
Per a una exportació fora de la UE amb divisa estrangera:
Tipus d’IVA: 0 EX.
País del comprador: el país no UE.
Tipus de canvi: el del dia anterior a la data d’IVA, segons la taula del BCE o NBP.
No feu servir zw (exempt) per a exportacions — Una exportació és 0 EX (zero-rate per exportació, P_13_6_3). Si utilitzeu zw, l’import queda duplicat entre les caselles domèstiques zero-rate i exempció, i KSeF rebutja o distorsiona la declaració.
A la fitxa d’una factura emesa veureu l’estat actual, el Numer KSeF un cop registrada, i el rebut UPO.
Sending → Registered → (QR + Numer KSeF + UPO)
↘ Error
Sending — B2Brouter ha signat i enviat el document. El registre efectiu a KSeF pot trigar uns minuts, sobretot en hores punta o al tancament del mes.
Registered ✅ — KSeF ha validat i assignat el Numer KSeF (NrKSeF). El QR de la factura impresa passa a mostrar aquest número i queda disponible el justificant oficial de registre (vegeu sota).
Error ❌ — KSeF ha rebutjat el document. El motiu apareix a la fitxa (codi + descripció en polonès).
El QR apareix de seguida, però això no vol dir que KSeF hagi acceptat la factura — B2Brouter genera el codi QR localment a partir del hash criptogràfic, el NIP i la data: és visible immediatament, fins i tot si la factura acabarà en error. L’únic indicador fiable d’acceptació és l’estat Registered. Si l’estat és Error, la factura no està registrada a KSeF independentment del QR o l’enllaç generats. Mentre la factura estigui Sending, el QR porta l’etiqueta OFFLINE.
Què és. L’UPO (Urzędowe Poświadczenie Odbioru, en català Acusament Oficial de Recepció) és el justificant que emet KSeF quan accepta i registra la factura. Funciona com un acusament de rebut administratiu: és la prova legal, amb valor fiscal, que heu complert l’obligació de registrar la factura a KSeF en un moment concret.
Tècnicament és un document XML signat digitalment pel Ministeri de Finances polonès. Conté el Numer KSeF (NrKSeF) assignat a la factura, la marca de temps exacta del registre i la signatura del Ministeri. No és un PDF visual — és una prova legal llegible per màquina.
D’on surt. El genera KSeF al moment de validar i acceptar la factura. No el genera B2Brouter ni vosaltres.
Com confirmar el registre des de B2Brouter. Quan la factura passa a Registered, obriu el tax report KSeF associat (enllaçat des de la fitxa de la factura). A la pestanya Activitat hi veureu l’event d’enviament correcte amb el Numer KSeF assignat — confirmació que KSeF ha rebut, validat i registrat el document.
Com obtenir el fitxer XML de l’UPO per al vostre arxiu comptable. El fitxer original queda disponible per dues vies:
Des del portal oficial de KSeF — ap.ksef.mf.gov.pl/web (o ap-test.ksef.mf.gov.pl/web per a l’entorn de proves). Accedint amb el vostre sistema d’identitat fiscal, podeu consultar i descarregar els UPOs del vostre compte directament del Ministeri — són l’original oficial.
Via API de B2Brouter — si integreu amb l’API, l’UPO està disponible com a adjunt del tax report. Vegeu la Guia KSeF per a desenvolupadors.
Conserveu els UPOs amb la factura — Tenen valor jurídic davant d’una inspecció fiscal. Descarregueu-los de KSeF o via API i arxiveu-los junt amb la factura original.
Obriu la factura i llegiu el codi + descripció de l’error.
Corregiu les dades problemàtiques (contacte, NIP, imports…).
Torneu a enviar la factura. B2Brouter reintenta el registre a KSeF amb les dades corregides.
Excepció — número de factura ja vist per KSeF — Si el rebuig ve del fet que el número de factura ja s’ha utilitzat en un enviament anterior, no podreu reenviar el mateix document: elimineu-lo, corregiu les dades i creeu una factura nova amb número diferent.
Una factura rectificativa (faktura korygująca) modifica una factura KSeF anterior. El document enllaça l’original (DaneFaKorygowanej) i reexpressa les línies afectades amb indicació de l’estat anterior i nou.
Crear factura rectificativa — B2Brouter omple automàticament el número KSeF, el número de factura i la data de l’original.
Indiqueu el Tipus d’efecte (TypKorekty):
1 — Efecte a la data de la factura original. Ús: correccions d’errors existents en emetre (import mal calculat, tipus d’IVA erroni).
2 — Efecte a la data de la factura rectificativa. Ús: fets posteriors (devolucions, descomptes post-venda).
3 — Efecte a una data diferent — indiqueu-la explícitament.
Actualitzeu les línies al nou estat (quantitats, preus, tipus d’IVA).
Si voleu afegir un motiu textual de la correcció (p. ex. «Korekta ilości — dostawa niepełna») o qualsevol text legal associat, escriviu-lo al camp Notes de la factura: s’envia al peu oficial del document (Stopka/Informacje/StopkaFaktury) i és visible al PDF de KSeF.
Emetre i enviar.
Estat «abans / després» — La rectificativa que emeteu des del formulari porta directament les línies amb els valors nous; aquest és el cas habitual i suficient per a la majoria de correccions. Si necessiteu la representació formal abans/després (línies originals anul·lades més les noves al mateix document, amb marcador Stan przed per línia), aquesta opció només és accessible via API: vegeu la Guia per a desenvolupadors.
Un cop KSeF està activat al compte, el vostre NIP queda registrat com a receptor i els proveïdors polonesos us hi poden enviar factures directament.
Despeses → hi trobareu totes les factures KSeF rebudes.
Obriu una factura per veure’n el detall.
On és el Numer KSeF d’una factura rebuda — El número KSeF oficial (NrKSeF) no apareix sobre la imatge del PDF preview, sinó a la secció Activitat de la factura rebuda (format XXXXXXXXXX-AAAAMMDD-XXXXXXXXXXXX-XX). El QR només és visible al PDF si el proveïdor l’ha inclòs a la seva imatge.
Una factura que el proveïdor diu haver emès però no apareix a Despeses — Primer verifiqueu que el PDF que us ha enviat el proveïdor porti codi QR de KSeF. Sense QR, la factura no s’ha enviat via KSeF — el proveïdor potser no ha completat el registre. Si hi ha QR, escanegeu-lo i copieu-ne l’URL: amb aquesta URL podem comprovar si el document existeix realment a KSeF.
Nova — rebuda a B2Brouter, pendent de la vostra revisió.
Llegida — l’heu obert almenys un cop.
Aprovada / Rebutjada — l’estat que li heu assignat (no s’envia cap missatge al proveïdor; KSeF no té un canal d’acceptació/rebuig equivalent al de Peppol).
Certificat rebutjat malgrat la contrasenya correcta — el PKCS#12 està xifrat amb un algoritme antic (RC2-40bit), típic d’exportacions fetes des de Windows antic. Re-exporteu amb 3DES o AES (vegeu § 1).
450 - Nip nabywcy: '…' jest nieprawidłowy — NIP del comprador invàlid. Comproveu 10 xifres + dígit de control. Per a contactes UE, useu el número d’IVA UE sense prefix (vegeu § 2).
KodUE: 'GR' is not an element of the set — Grècia al camp fiscal UE ha d’anar com a EL, no GR. Editeu el contacte i corregiu-ho.
«Contact Email can’t be blank» — el transport del contacte és e-mail però no hi ha adreça. Afegiu-hi un e-mail o canvieu el transport.
Estat Error però s’ha generat QR i URL — normal. El QR es calcula en local i no depèn de l’acceptació de KSeF. L’estat Error és autoritatiu: la factura no està registrada.
Factura que el proveïdor diu haver emès però no apareix a Despeses — comproveu que el PDF del proveïdor porti codi QR de KSeF. Sense QR, no s’ha registrat realment.
Compte no polonès que intenta usar KSeF com a transport — KSeF només està disponible per a comptes amb NIP polonès. Useu Peppol o e-mail en aquest contacte.
Resum d’IVA mostra «23% lub 22%» — etiqueta oficial del template del Ministeri, que combina el tipus històric (22 %) i l’actual (23 %) en un únic camp. No és un error.
Camp «Nazwa banku» (nom del banc) buit — KSeF no exigeix el nom del banc i B2Brouter no el popula automàticament. Si el necessiteu, afegiu-lo al camp Notes.
Aquest manual descriu la UI. Si integreu amb B2Brouter via API, la referència oficial és la Guia KSeF per a desenvolupadors — cobreix els endpoints Tax Report Settings, Tax Reports, Invoices i Contacts, el mapeig complet entre JSON i FA(3), els webhooks de seguiment d’estats i la descàrrega de l’UPO.
Autenticació per API key estàtica (capçalera X-B2B-API-Key) + versió d’API (X-B2B-API-Version). Les funcionalitats específiques de KSeF requereixen versió 2025-10-13 o posterior.
