Llegir els errors de KSeF en llenguatge clar: codi, causa, camp, solució

Els missatges d'error de KSeF són la primera queixa d'UX del mercat després del llançament. El sistema retorna codis numèrics d'excepció (21401, 21405, 21301, 440) amb descripcions de nivell desenvolupador com "Dokument nie jest zgodny ze schemą XSD". Cap proveïdor polonès no ofereix una explicació en llenguatge clar. Els codis són deterministes, cosa que els fa ideals per a una traducció fonamentada en cites: cada codi mapeja a una causa, un camp fallit i una solució.

El descodificador

21401: "Dokument nie jest zgodny ze schemą XSD"

Llenguatge clar: El vostre XML de factura no coincideix amb l'esquema FA(3). L'estructura és incorrecta.

Causa: L'XML es va generar des d'una plantilla obsoleta (FA(2) en lloc de FA(3)), conté caràcters no vàlids (bytes BOM), té elements en ordre incorrecte o li falten elements obligatoris.

Camp fallit: La resposta d'error inclou l'XPath de l'element fallit. Busqueu la ruta del camp a la resposta.

Solució: Regenereu la factura des d'una plantilla FA(3) actual. Actualitzeu el programari de facturació a l'última versió. No editeu l'XML a mà.

21405: Error de validació d'entrada

Llenguatge clar: Un camp concret conté dades en format incorrecte. L'estructura de l'XML és correcta, però el contingut d'un camp no supera la validació.

Causa: NIP amb guions o espais, data en format incorrecte, camp numèric amb coma en lloc de punt, o KursWaluty amb menys de 6 decimals.

Camp fallit: La resposta d'error anomena el camp concret. Sospitosos habituals: NIP (comprador o venedor), P_1 (data d'emissió), KursWaluty.

Solució: Corregiu les dades d'origen a la fitxa del client o al formulari de factura. Per al NIP: treieu tots els guions, espais i prefixos "PL". Per a les dates: useu AAAA-MM-DD. Per als decimals: useu punt, no coma. Reenvieu.

21301: "brak autoryzacji"

Llenguatge clar: No teniu permís per emetre factures per al NIP de la capçalera de la factura.

Causa: El token ha caducat, es va emetre per a un NIP distint o els permisos no inclouen drets d'emissió per a aquesta entitat.

Camp fallit: NIP de la capçalera de la factura davant NIP del token.

Solució: Regenereu el token amb els abasts correctes per al NIP emissor. Si feu servir un inici de sessió personal (Profil Zaufany), canvieu a autenticació per token. Si sou una gestoria, verifiqueu que el client us va concedir drets d'emissió sobre el seu NIP.

440: Duplicat

Llenguatge clar: Ja existeix a KSeF una factura amb el mateix número del mateix emissor.

Causa: Vau reenviar una factura que ja s'havia enviat amb èxit. El primer enviament va funcionar però no vau comprovar l'estat abans de reenviar.

Camp fallit: Número de factura (NrFaktury).

Solució: Consulteu KSeF pel vostre número de factura. Si el primer enviament va tenir èxit (estat 200), feu servir el número KSeF existent. No creeu un duplicat. Si el primer enviament va fallar de veritat, corregiu l'error i reenvieu amb el mateix número de factura.

Estat 100 o 150: No és un error

Llenguatge clar: La factura s'està processant. Espereu.

Causa: KSeF va rebre la factura i l'està processant. El temps de processament varia de segons a hores sota càrrega.

Solució: Consulteu la mateixa sessió. No reenvieu. Reenviar crea un duplicat.

HTTP 500, 503, 429: Error del servidor

Llenguatge clar: KSeF està sobrecarregat o us està limitant la taxa de peticions.

Causa: Trànsit del període de llançament, problemes transitoris d'infraestructura o massa peticions en una finestra curta.

Solució: Reintenteu amb espera progressiva. Si l'error persisteix, canvieu al mode offline24. Emeteu la factura localment i envieu-la abans del dia laborable següent.

Per què cap proveïdor no ho ofereix

Els codis d'error són deterministes. Mapejen a causes i solucions fixes. Un motor d'explicació és tècnicament senzill: una taula de correspondència de codi a causa-camp-solució, amb cites de la documentació oficial.

Cap proveïdor polonès no ho ofereix perquè els productes establerts es van construir abans de KSeF i tracten la gestió d'errors com a secundària. Els missatges d'error són respostes crues de l'API embolicades en una capa fina d'interfície. L'usuari veu "21401" i ha de buscar una explicació a internet, on troba articles de granges de continguts amb codis inventats.

L'oportunitat és oferir el motor d'explicació com a eina gratuïta i realment útil. Cada codi d'error de la taxonomia real, mapejat a llenguatge clar, amb cites de la documentació OpenAPI oficial. Sense codis inventats. Sense procediments fabricats. L'usuari busca "błąd 21401 KSeF" i troba una pàgina que diu: "El vostre XML no coincideix amb l'esquema FA(3). Aquest és el motiu. Aquest és el camp a corregir. Així es corregeix."

Aquesta pàgina posiciona. Posiciona perquè és precisa, té fonts i és útil. Posiciona perquè cada alternativa de granja de continguts és incorrecta. La precisió és el fossat defensiu.

Compliment del Reglament d'IA

Si el motor d'explicació usa IA (per exemple, un model de llenguatge per generar el text en llenguatge clar a partir del codi i el context), l'article 50 del Reglament d'IA exigeix revelar que l'usuari interactua amb un sistema d'IA i el marcatge llegible per màquina del contingut generat per IA. Des del 2 d'agost de 2026, és obligatori.

El disseny més segur: una taula de correspondència determinista, no un model de llenguatge. Els codis són fixos. Les causes són fixes. Les solucions són fixes. Una taula de correspondència és més precisa, més ràpida i està exempta de les obligacions de transparència del Reglament d'IA. Useu IA per al que es beneficia del raonament (suggeriments de paràmetres, redacció). Useu una taula de correspondència per al que és determinista (codis d'error).

Aquest material és informació de caràcter general i no constitueix assessorament legal ni fiscal. Per a una situació concreta, verifiqueu la normativa vigent o consulteu un assessor qualificat.