Estructura XML FA(3): guía de KSeF para desarrollo

La estructura XML FA(3) es el esquema que KSeF utiliza para las facturas estructuradas emitidas desde el 1 de febrero de 2026. Trátala como tres contratos: el XSD define la forma del XML, la normativa polaca del IVA determina los datos obligatorios y la transacción activa las ramas condicionales. Valida los tres antes del envío. La aceptación es el estado final de KSeF, no la respuesta a la subida.

Esta es una guía técnica, no asesoramiento fiscal. Confirma con un profesional el tratamiento del IVA y los datos exigidos para cada tipo de factura.

¿Qué es la estructura XML FA(3)?

FA(3) es la estructura lógica del Ministerio de Finanzas polaco para una factura estructurada. No es un PDF ni una plantilla visual: es un contrato XML que define qué elementos pueden aparecer, dónde, cuántas veces y con qué tipos y formatos.

El manual de KSeF 2.0 marca una frontera esencial. La estructura regula lo que el XML debe o puede contener, pero el artículo 106e de la Ley del IVA sigue determinando qué información exige cada factura. FA(3) también incluye campos opcionales, como los datos de contacto, que la ley no suele exigir.

No lo reduzcas a «XML válido». minOccurs="0" solo permite omitir el elemento en el XSD; no dice que pueda faltar legalmente en todos los casos. Y un campo rellenado en un ejemplo oficial no es obligatorio por ese mero hecho.

¿Qué espacio de nombres y cabecera debes usar?

Usa el espacio de nombres del XSD FA(3) oficial:

http://crd.gov.pl/wzor/2025/06/25/13775/

La barra final importa. El esquema utiliza elementos cualificados; añadir después una ubicación de esquema no convierte un <Faktura> sin espacio de nombres en el mismo documento.

El ejemplo oficial del cliente Java muestra esta cabecera:

<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek>
    <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
    <WariantFormularza>3</WariantFormularza>
    <DataWytworzeniaFa>2026-08-28T09:30:00Z</DataWytworzeniaFa>
    <SystemInfo>YourApp 4.2</SystemInfo>
  </Naglowek>
  <!-- Remaining sections in XSD order -->
</Faktura>

Centraliza el espacio de nombres, kodSystemowy, wersjaSchemy y la variante en un serializador versionado. Una versión futura debe activar una selección explícita y sus fixtures, no una sustitución global de cadenas.

Genera XML 1.0 en UTF-8 sin BOM. Las reglas de verificación permiten omitir la declaración XML, pero no declarar otra codificación. KSeF también rechaza instrucciones de procesamiento y determinados rangos Unicode. Normaliza el texto antes de serializarlo.

¿Cuáles son las ocho secciones principales de FA(3)?

El orden forma parte del contrato. El XSD agrupa elementos en sequence y choice; un mapeador genérico puede emitir todos los valores correctos en el orden equivocado. Declara el orden y cúbrelo con una prueba XSD. Añade las secciones condicionales solo si el modelo contiene ese rol o función. Los adjuntos tienen además activación, límites y flujo propios.

¿Qué aspecto tiene el esqueleto de una factura FA(3)?

Este esqueleto es deliberadamente incompleto: no está listo para copiar, no es un mínimo del esquema ni basta legalmente.

<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek>
    <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
    <WariantFormularza>3</WariantFormularza>
    <DataWytworzeniaFa>2026-08-28T09:30:00Z</DataWytworzeniaFa>
    <SystemInfo>YourApp 4.2</SystemInfo>
  </Naglowek>
  <Podmiot1><DaneIdentyfikacyjne><NIP>1234567890</NIP><Nazwa>Example Seller sp. z o.o.</Nazwa></DaneIdentyfikacyjne></Podmiot1>
  <Podmiot2><DaneIdentyfikacyjne><NIP>9876543210</NIP><Nazwa>Example Buyer sp. z o.o.</Nazwa></DaneIdentyfikacyjne></Podmiot2>
  <Fa>
    <KodWaluty>PLN</KodWaluty><P_1>2026-08-28</P_1><P_2>FV/2026/08/1042</P_2><P_15>123.00</P_15>
    <Adnotacje><!-- Applicable markers and branches --></Adnotacje>
    <RodzajFaktury>VAT</RodzajFaktury>
    <FaWiersz><NrWierszaFa>1</NrWierszaFa><P_7>Software subscription</P_7><P_8A>szt.</P_8A><P_8B>1</P_8B><P_9A>100.00</P_9A><P_11>100.00</P_11><P_12>23</P_12></FaWiersz>
  </Fa>
</Faktura>

El mínimo cambia según el tipo, las partes, el IVA, el pago, las correcciones y los anticipos. Un documento hecho solo para satisfacer cardinalidades puede omitir datos legales. Parte de un modelo tipado y fixtures por escenario.

¿Cómo se mapean los identificadores de vendedor y comprador?

KSeF usa Podmiot2/DaneIdentyfikacyjne/NIP para poner la factura a disposición del comprador polaco. Ocultarlo en NrID puede parecer razonable internamente y romper esa entrega.

Guarda por separado tax_identifier_kind, country_code, identifier y has_no_identifier. Valida ramas excluyentes antes de serializar. Elimina separadores de presentación, pero no «corrijas» en silencio un dato ambiguo. Producción comprueba el dígito de control del NIP de un modo que TEST no replica; valídalo en tu aplicación.

¿Cómo debes modelar Fa, los totales y las líneas?

Fa contiene la operación: moneda (KodWaluty), fecha (P_1), número del vendedor (P_2), totales, anotaciones, tipo (RodzajFaktury), líneas FaWiersz y, cuando proceda, pago.

No conviertas los nombres XML en tu modelo de negocio. Modela dinero, categorías fiscales, cantidades, fechas, partes y tipo con tipos de dominio y después mapéalos. Para cada escenario, comprueba la conciliación entre líneas y totales, la política de redondeo, P_15, los formatos invariantes, que P_1 no sea futuro y que P_2 sea estable.

La clave de duplicado combina NIP del vendedor, RodzajFaktury y P_2. Un reintento debe reconciliar la misma factura lógica, no generar otro número. Conserva idempotencia alrededor de la factura y la referencia KSeF.

Las anotaciones necesitan pruebas por escenario. Copiar marcadores negativos del ejemplo puede crear un documento válido pero falso. Deriva las ramas de los hechos y prueba exención, inversión del sujeto pasivo, pago fraccionado, margen y cada caso admitido.

¿Cómo validas FA(3) en local antes de enviarlo?

1. Congela una factura tipada con partes, líneas, IVA, totales, fechas y tipo.
2. Aplica reglas de negocio y devuelve errores de campo comprensibles.
3. Serializa de forma determinista: XML 1.0, UTF-8 sin BOM, espacio de nombres, orden y formatos invariantes.
4. Valida con el XSD fijado y sus definiciones importadas; registra checksum y URL.
5. Congela los bytes. Calcula tamaño y hash sobre la secuencia que realmente cifras y subes.
6. Guarda diagnósticos: versión del serializador, referencia al snapshot, hash, tamaño y resultado. Protege el XML como dato financiero sensible.

Las reglas oficiales limitan una factura sin adjunto a 1 MB y con adjunto a 3 MB. La validación XSD no cubre los límites del servicio. Usa fixtures de IVA nacional, comprador UE, tercer país, consumidor, corrección, anticipo, exención y cada régimen compatible.

¿Cómo pruebas en TEST, DEMO y producción?

La matriz oficial de entornos presenta TEST para integración, DEMO como similar a producción y PRD como el entorno donde las facturas tienen efectos jurídicos. No envíes datos reales a TEST ni DEMO. TEST admite certificados autofirmados y sus datos no deben considerarse confidenciales: usa identidades y NIP sintéticos.

Prueba mapeo y XSD en local; envía escenarios sintéticos a TEST; verifica credenciales, permisos, consulta de estado y UPO en DEMO; y promueve el mismo serializador a PRD con despliegue controlado y monitorización. TEST no demuestra que un NIP sea válido en producción. Versiona capacidades por entorno, porque una API puede llegar antes a TEST.

¿Cuándo está aceptada realmente una factura enviada?

El envío en sesión es asíncrono. La API puede aceptar el trabajo y devolver una referencia antes de aceptar la factura. Guarda esa referencia al instante y pasa la factura a processing.

La guía oficial de estado y UPO documenta estados, fallos y obtención del UPO. Consulta con espera progresiva y distingue: generada y validada; enviada con referencia; en proceso; rechazada; aceptada con número KSeF; y UPO almacenado.

Solo la ruta aceptada debe mostrar el número KSeF como prueba final. Guarda el UPO con metadatos resistentes a alteraciones y reconcilia sesiones largas. HTTP 202 significa «en cola», no «factura correcta».

¿Desarrollar FA(3) o usar KSeF Kit?

Desarrolla la integración si FA(3) es una función central, tienes fuentes distintas de Stripe o necesitas escenarios fiscales especializados. Presupuesta seguimiento del esquema, fixtures, credenciales, entornos, monitorización y operación, no solo XML.

Si Stripe es la fuente, KSeF Kit convierte facturas finalizadas de Stripe a FA(3), las envía y guarda el número KSeF y el UPO. Su documentación de configuración cubre la conexión con Stripe y KSeF y los flujos de prueba y producción.

No sustituye datos fiscales correctos ni garantiza por sí solo el cumplimiento. Sí elimina una superficie importante: serializador, cifrado, subida, máquina de estados y entrega de pruebas. En ambos caminos, exige datos de dominio correctos, XML FA(3) válido, procesamiento satisfactorio y pruebas conservadas. Consulta más guías en el archivo de ingeniería de cumplimiento.