Campos de factura JSON a XML KSeF FA(3)

Disponible a partir de la versión 2025-10-13

Esta guía detalla el mapeo entre los campos de la API de facturas de B2Brouter, los Términos de Negocio (BT) correspondientes definidos por el estándar europeo de facturación electrónica (EN 16931) y las rutas XML del formato KSeF FA(3) (Sistema Nacional de Facturación Electrónica de Polonia).

Su propósito es ayudar a entender cómo los datos de factura enviados en formato JSON mediante la API de facturas corresponden a la estructura XML KSeF FA(3). Solo se incluyen los campos que se mapean efectivamente durante la generación del informe fiscal.

Nota

KSeF utiliza un esquema XML específico de Polonia (variante FA 3, versión de esquema 1-0E) que difiere significativamente de los formatos EN 16931 como UBL o CII. No todos los Términos de Negocio EN 16931 tienen un equivalente directo en KSeF, y KSeF introduce campos específicos de Polonia no presentes en el estándar europeo.

Nota: La información del vendedor/proveedor (Podmiot1) se rellena automáticamente a partir de la configuración de tu cuenta. La información del comprador/cliente (Podmiot2) se rellena a partir del contacto de la factura. Si necesitas control directo sobre todos los campos, considera usar la API de informes fiscales en su lugar.

Mapeo a nivel de cabecera

BT ID	Término de negocio	Campo API (B2Brouter)	KSeF FA(3) XPath
BT-1	Número de factura	invoice.number	Fa/P_2
BT-2	Fecha de emisión	invoice.date	Fa/P_1
BT-3	Código de tipo de factura	invoice.type_document Derivado: por defecto VAT; KOR si es factura rectificativa; ZAL si es anticipo; UPR si es simplificada	Fa/RodzajFaktury
BT-5	Moneda de la factura	invoice.currency	Fa/KodWaluty
BT-7	Fecha del punto impositivo	invoice.tax_point_date	Fa/P_6
BT-9	Fecha de vencimiento	invoice.due_date	Fa/Platnosc/TerminPlatnosci/Termin
BT-25	Número de factura anterior	invoice.invoice_references[reference_type=amend].number (v2026-04-20+) o invoice.amended_number (versiones anteriores)	Fa/DaneFaKorygowanej/NrFaKorygowanej
BT-26	Fecha de factura anterior	invoice.invoice_references[reference_type=amend].date (v2026-04-20+) o invoice.amended_date (versiones anteriores)	Fa/DaneFaKorygowanej/DataWystFaKorygowanej
—	Tipo de cambio	invoice.exchange_rate	Fa/KursWalutyZ
BT-10	Referencia del comprador	invoice.buyer_reference	Podmiot2/NrKlienta
BT-13	Referencia de orden de compra	invoice.ponumber	Fa/WarunkiTransakcji/Zamowienia/NrZamowienia
BT-92	Fecha de orden de compra	invoice.order_date	Fa/WarunkiTransakcji/Zamowienia/DataZamowienia
BT-14	Referencia de pedido de venta	invoice.sales_order_reference	Fa/DodatkowyOpis (par clave-valor)
BT-16	Referencia de aviso de despacho	invoice.delivery_note_number	Fa/WZ
—	Código de efecto de corrección	invoice.amend_code_tax o tax_report_setting.credit_note_code	Fa/TypKorekty (solo para tipos KOR)

Mapeo a nivel de pago

BT ID	Término de negocio	Campo API (B2Brouter)	KSeF FA(3) XPath
BT-9	Fecha de vencimiento	invoice.due_date	Fa/Platnosc/TerminPlatnosci/Termin
BT-81	Código de medio de pago	invoice.payment_method (mapeado a códigos KSeF)	Fa/Platnosc/FormaPlatnosci
BT-84	IBAN de la cuenta financiera	invoice.bank_account.iban	Fa/Platnosc/RachunekBankowy/NrRB
BT-84-0	Número de cuenta financiera	invoice.bank_account.number (alternativo si no hay IBAN)	Fa/Platnosc/RachunekBankowy/NrRB
BT-85	Nombre de la cuenta financiera	invoice.bank_account.name	Fa/Platnosc/RachunekBankowy/NazwaBanku
BT-86	BIC de la cuenta financiera	invoice.bank_account.bic	Fa/Platnosc/RachunekBankowy/SWIFT
—	Indicador de pago realizado	Derivado: 1 cuando payable_amount = 0 y total > 0	Fa/Platnosc/Zaplacono
—	Fecha de pago (cuando está pagado)	invoice.due_date (cuando Zaplacono=1)	Fa/Platnosc/DataZaplaty

Nota: KSeF no admite datos de cuenta de tarjeta (BT-87, BT-88), mandatos de domiciliación (BT-89), referencias de acreedor (BT-90), texto de condiciones de pago (BT-20) ni información de remesa (BT-83).

Mapeo de partes

Este mapeo se describe para una factura emitida. Si deseas mapear una factura recibida, intercambia Podmiot1 y Podmiot2.

Podmiot1 (Vendedor/Proveedor)

El Podmiot1 se rellena automáticamente a partir de la configuración de tu cuenta. Incluye el nombre de la empresa, el NIP (número fiscal polaco) y la dirección.

BT ID	Término de negocio	Campo API (B2Brouter)	KSeF FA(3) XPath
—	Prefijo de país del vendedor	account.country (en mayúsculas)	Podmiot1/PrefiksPodatnika
BT-31	NIP del vendedor	account.tin_value (sin prefijo de país)	Podmiot1/DaneIdentyfikacyjne/NIP
BT-27	Nombre del vendedor	account.name	Podmiot1/DaneIdentyfikacyjne/Nazwa
BT-40	País del vendedor	account.country (en mayúsculas)	Podmiot1/Adres/KodKraju
BT-35	Calle del vendedor	account.address	Podmiot1/Adres/AdresL1
BT-37,38	Código postal + ciudad del vendedor	account.postalcode + account.city	Podmiot1/Adres/AdresL2
BT-29-0	GLN del vendedor	account.cin_value (si cin_scheme = 88)	Podmiot1/Adres/GLN
BT-42	Teléfono de contacto del vendedor	account.phone	Podmiot1/DaneKontaktowe/Telefon
BT-43	Email de contacto del vendedor	account.email	Podmiot1/DaneKontaktowe/Email
—	REGON del vendedor	account.routing_codes.cinX (esquema 8037)	Stopka/Rejestry/REGON
—	KRS del vendedor	account.routing_codes.cinX (esquema 8036)	Stopka/Rejestry/KRS
—	BDO del vendedor	account.routing_codes.cinX (esquema 8038)	Stopka/Rejestry/BDO

Podmiot2 (Comprador/Cliente)

BT ID	Término de negocio	Campo API (B2Brouter)	KSeF FA(3) XPath
BT-48	NIF del comprador	invoice.contact.tin_value	PL: Podmiot2/DaneIdentyfikacyjne/NIP UE: Podmiot2/DaneIdentyfikacyjne/NrVatUE No UE: Podmiot2/DaneIdentyfikacyjne/NrID
—	País fiscal del comprador (UE)	invoice.contact.country (en mayúsculas)	Podmiot2/DaneIdentyfikacyjne/KodUE (solo UE)
—	País fiscal del comprador (no UE)	invoice.contact.country (en mayúsculas)	Podmiot2/DaneIdentyfikacyjne/KodKraju (solo no UE)
—	Indicador sin NIF	Derivado: 1 cuando contact.tin_value está en blanco	Podmiot2/DaneIdentyfikacyjne/BrakID
BT-44	Nombre del comprador	invoice.contact.name	Podmiot2/DaneIdentyfikacyjne/Nazwa
BT-55	País del comprador	invoice.contact.country (en mayúsculas)	Podmiot2/Adres/KodKraju
BT-50	Calle del comprador	invoice.contact.address	Podmiot2/Adres/AdresL1
BT-52,53	Código postal + ciudad del comprador	invoice.contact.postalcode + invoice.contact.city	Podmiot2/Adres/AdresL2
BT-46-0	GLN del comprador	invoice.contact.cin_value (si cin_scheme = 88)	Podmiot2/Adres/GLN

Mapeo de terceros (Podmiot3)

KSeF admite múltiples roles de terceros mediante el elemento Podmiot3. Se genera un Podmiot3 cuando hay información de entrega o cuando la factura tiene un objeto third_party (disponible desde v2026-04-20).

Códigos de rol

Código de rol	third_party.role en B2Brouter	Descripción
2	delivery_recipient	Destinatario de la entrega
3	original_supplier	Entidad original (cedida/transformada)
4	additional_buyer	Comprador adicional
5	invoice_issuer	Emisor de factura en nombre del contribuyente
6	payer	Pagador en nombre del comprador
7	local_government_unit_issuer	Entidad de gobierno local — emisor
8	local_government_unit_recipient	Entidad de gobierno local — receptor (JST)
9	vat_group_member_issuer	Miembro del grupo IVA — emisor
10	vat_group_member_recipient	Miembro del grupo IVA — receptor (GV)
11	employee	Empleado

Entrega (rol 2)

La información de entrega se mapea a Podmiot3 con el código de rol 2 cuando invoice.delivery_address está presente. La dirección de entrega también se duplica en Fa/WarunkiTransakcji/Transport/WysylkaDo.

BT ID	Término de negocio	Campo API (B2Brouter)	KSeF FA(3) XPath
BT-70	Nombre de la parte de entrega	invoice.delivery_party_name	Podmiot3/DaneIdentyfikacyjne/Nazwa
BT-71	ID de ubicación de entrega (GLN)	invoice.delivery_location_id (si el tipo es GLN/088)	Podmiot3/Adres/GLN
BT-75	Calle de entrega	invoice.delivery_address	Podmiot3/Adres/AdresL1 y Fa/WarunkiTransakcji/Transport/WysylkaDo/AdresL1
BT-77,78	Código postal + ciudad de entrega	invoice.delivery_postalcode + invoice.delivery_city	Podmiot3/Adres/AdresL2 y Fa/WarunkiTransakcji/Transport/WysylkaDo/AdresL2
BT-80	País de entrega	invoice.delivery_country	Podmiot3/Adres/KodKraju y Fa/WarunkiTransakcji/Transport/WysylkaDo/KodKraju
—	Rol del tercero	Fijo: 2 (Receptor)	Podmiot3/Rola

Nota: KSeF no admite fecha de entrega (BT-72) ni campos de período de entrega.

JST / GV / Otros roles (roles 3–11) — v2026-04-20+

Cambiado en la versión 2026-04-20

Soporte de terceros más allá del destinatario de entrega.

Término de negocio	Campo API (B2Brouter)	KSeF FA(3) XPath
Nombre del tercero	invoice.third_party.name	Podmiot3/DaneIdentyfikacyjne/Nazwa
NIF del tercero	invoice.third_party.tin_value	Podmiot3/DaneIdentyfikacyjne/NIP (PL), NrVatUE (UE), o NrID (no UE)
Dirección del tercero	invoice.third_party.address	Podmiot3/Adres/AdresL1
Código postal + ciudad del tercero	invoice.third_party.postalcode + invoice.third_party.city	Podmiot3/Adres/AdresL2
País del tercero	invoice.third_party.country	Podmiot3/Adres/KodKraju
Rol del tercero	invoice.third_party.role → código de rol	Podmiot3/Rola
Indicador JST	invoice.apply_to_local_government_unit	Podmiot2/JST (1 cuando es verdadero, 2 cuando es falso)
Indicador GV	invoice.apply_to_vat_group_member	Podmiot2/GV (1 cuando es verdadero, 2 cuando es falso)

Mapeo a nivel de línea de factura (FaWiersz)

Todos los atributos listados en la siguiente tabla son propiedades de objetos contenidos en el array: invoice.invoice_lines_attributes[]. La columna Campo API hace referencia a las claves dentro de cada objeto de línea de factura.

Para facturas ordinarias (VAT, KOR, UPR, ROZ), las líneas se representan como elementos FaWiersz. Para facturas de anticipo (ZAL, KOR_ZAL), las líneas se representan como elementos ZamowienieWiersz.

BT ID	Término de negocio	Campo API (objeto de línea)	KSeF FA(3) XPath
BT-126	ID de línea de factura	position	Fa/FaWiersz/NrWierszaFa
BT-153	Nombre del artículo	description	Fa/FaWiersz/P_7
BT-130	Cantidad facturada (código de unidad)	unit (consultar la referencia de la API para la lista de códigos)	Fa/FaWiersz/P_8A
BT-129	Cantidad facturada	quantity	Fa/FaWiersz/P_8B
BT-155	Identificador del vendedor	article_code	Fa/FaWiersz/Indeks
BT-157	Identificador estándar (GTIN)	article_code2	Fa/FaWiersz/GTIN
BT-146	Precio unitario	price	Fa/FaWiersz/P_9A
-	Precio unitario con descuento	Derivado de allowance_charges_attributes[]{allowance_charge_indicator: "allowance"} importe / quantity de la línea	Fa/FaWiersz/P_10
BT-131	Importe neto de la línea	extension_amount (si no se proporciona, se calculará)	Fa/FaWiersz/P_11
—	Importe de impuesto de la línea	Calculado a partir de los impuestos	Fa/FaWiersz/P_11Vat
—	Código de impuesto	Derivado de las características del impuesto	Fa/FaWiersz/P_12

Mapeo de propiedades adicionales del artículo (DodatkowyOpis por línea)

Cada línea de factura puede contener propiedades adicionales de clave-valor que se mapean a elementos DodatkowyOpis a nivel de línea en el XML de KSeF.

Todos los atributos listados en la siguiente tabla son propiedades de objetos contenidos en el array: invoice.invoice_lines_attributes[].additional_item_properties_attributes[].

BT ID	Término de negocio	Campo API (objeto de propiedad adicional)	KSeF FA(3) XPath
—	Referencia de número de línea	position de la línea padre	Fa/DodatkowyOpis/NrWiersza
BT-160	Nombre del atributo del artículo	name (máx. 255 caracteres)	Fa/DodatkowyOpis/Klucz
BT-161	Valor del atributo del artículo	value (máx. 255 caracteres)	Fa/DodatkowyOpis/Wartosc

Ejemplo JSON:

{
  "invoice": {
    "invoice_lines_attributes": [
      {
        "position": 1,
        "description": "Product A",
        "additional_item_properties_attributes": [
          { "name": "Color", "value": "Red" },
          { "name": "Size", "value": "XL" }
        ]
      }
    ]
  }
}

XML KSeF resultante:

<tns:DodatkowyOpis>
  <tns:NrWiersza>1</tns:NrWiersza>
  <tns:Klucz>Color</tns:Klucz>
  <tns:Wartosc>Red</tns:Wartosc>
</tns:DodatkowyOpis>
<tns:DodatkowyOpis>
  <tns:NrWiersza>1</tns:NrWiersza>
  <tns:Klucz>Size</tns:Klucz>
  <tns:Wartosc>XL</tns:Wartosc>
</tns:DodatkowyOpis>

Propiedad especial: unit_of_measure

Configurar una propiedad adicional con el nombre unit_of_measure permite especificar un código de unidad en texto libre para el campo P_8A de la línea en KSeF, reemplazando la lista estándar de códigos de unidad.

{
  "additional_item_properties_attributes": [
    { "name": "unit_of_measure", "value": "szt." }
  ]
}

Esta propiedad se utiliza directamente como el código de unidad de la línea (Fa/FaWiersz/P_8A) y no se emite como elemento DodatkowyOpis en la salida XML.

Mapeo de impuestos

Todos los atributos listados en la siguiente tabla son propiedades de objetos contenidos en el array: invoice.invoice_lines_attributes[].taxes_attributes[].

BT ID	Término de negocio	Campo API (objeto de impuesto)	Mapeo KSeF FA(3)
BT-118	Código de categoría fiscal	category (consultar lista de códigos)	Se usa para derivar el código de impuesto P_12
BT-119	Porcentaje de impuesto aplicable	percent	Se usa para derivar el código P_12 y las agregaciones P_13_x/P_14_x
BT-120	Motivo de exención fiscal	comment	Fa/Adnotacje/Zwolnienie/P_19A. También acepta un código P_12 de KSeF (zw, np I, np II, 0 KR, 0 WDT, 0 EX, oo) para reemplazar el valor derivado.

Agregación del desglose fiscal (P_13_x / P_14_x)

KSeF requiere que los importes de impuestos se agreguen por tipo a nivel de cabecera. Estos campos se calculan automáticamente a partir de los desgloses fiscales de la factura:

Campo KSeF	Descripción	Tipo/Categoría fiscal
P_13_1	Base imponible al tipo general	23% o 22%
P_14_1	Importe de impuesto al tipo general	23% o 22%
P_14_1W	Importe de impuesto al tipo general convertido a PLN	23% o 22% (solo facturas en moneda extranjera)
P_13_2	Base imponible al primer tipo reducido	8% o 7%
P_14_2	Importe de impuesto al primer tipo reducido	8% o 7%
P_14_2W	Importe de impuesto al primer tipo reducido convertido a PLN	8% o 7% (solo facturas en moneda extranjera)
P_13_3	Base imponible al segundo tipo reducido	5%
P_14_3	Importe de impuesto al segundo tipo reducido	5%
P_14_3W	Importe de impuesto al segundo tipo reducido convertido a PLN	5% (solo facturas en moneda extranjera)
P_13_6_1	Valor total de ventas internas al tipo cero	0% nacional (excluidos intracomunitarios y exportación)
P_13_6_2	Valor total de entregas intracomunitarias al 0%	0% bienes intracomunitarios
P_13_6_3	Valor total de exportaciones al 0%	0% exportación
P_13_7	Valor total de ventas exentas	Exento (categoría E, ámbito nacional)
P_13_8	Valor total de inversión del sujeto pasivo transfronteriza (np I)	Categoría AE, ámbito no nacional
P_13_10	Valor total de inversión del sujeto pasivo nacional	Categoría AE, ámbito nacional
P_15	Importe total a pagar (incluidos todos los impuestos)	Suma de todas las categorías

Nota

Los campos P_14_xW (importes de impuestos convertidos a PLN) solo se incluyen para facturas en monedas extranjeras. La conversión utiliza el exchange_rate proporcionado en la factura.