fix: support other recipient types

samupl · samupl · commit 52bcdedf6d93 · 2026-02-21T15:08:52.000+01:00
diff --git a/documentation/docs/reference/invoice-models.md b/documentation/docs/reference/invoice-models.md
@@ -62,16 +62,63 @@ issuer = Issuer(
 
 ## Subject (Recipient)
 
-Information about the invoice recipient (buyer).
+Information about the invoice recipient (buyer). The `identification_data` field accepts four identification types matching the FA(3) schema's `DaneIdentyfikacyjne` choices for `Podmiot2`.
+
+### Identification types
+
+**Polish company (NIP)**
 
 ```python
-from ksef.models.invoice import Subject, SubjectIdentificationData, Address
+from ksef.models.invoice import Subject, NipIdentification
 
 recipient = Subject(
-    identification_data=SubjectIdentificationData(
-        nip="0987654321",
-    ),
-    # Optional: buyer address
+    identification_data=NipIdentification(nip="0987654321"),
+)
+```
+
+> `SubjectIdentificationData` is a backwards-compatible alias for `NipIdentification`.
+
+**EU company (VAT)**
+
+```python
+from ksef.models.invoice import Subject, EuVatIdentification
+
+recipient = Subject(
+    identification_data=EuVatIdentification(eu_country_code="DE", eu_vat_number="123456789"),
+    name="Deutsche Firma GmbH",
+)
+```
+
+**Non-EU entity**
+
+```python
+from ksef.models.invoice import Subject, ForeignIdentification
+
+recipient = Subject(
+    identification_data=ForeignIdentification(country_code="US", tax_id="EIN123456"),
+    name="American Corp.",
+)
+```
+
+**Individual / no tax ID (B2C)**
+
+```python
+from ksef.models.invoice import Subject, NoIdentification
+
+recipient = Subject(
+    identification_data=NoIdentification(),
+    name="Jan Kowalski",
+)
+```
+
+### Full example with address
+
+```python
+from ksef.models.invoice import Subject, NipIdentification, Address
+
+recipient = Subject(
+    identification_data=NipIdentification(nip="0987654321"),
+    name="Firma Testowa Sp. z o.o.",
     address=Address(
         country_code="PL",
         city="Kraków",
@@ -87,11 +134,21 @@ recipient = Subject(
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `identification_data` | `SubjectIdentificationData` | Yes | Recipient NIP |
+| `identification_data` | `NipIdentification \| EuVatIdentification \| ForeignIdentification \| NoIdentification` | Yes | Buyer identification (see types below) |
+| `name` | `str` | No | Buyer name (maps to `Nazwa` in `Podmiot2`) |
 | `address` | `Address` | No | Buyer address (maps to `Adres` in `Podmiot2`) |
 | `jst` | `int` | No | Is the buyer a local government unit? `1` = yes, `2` = no (default: `2`) |
 | `gv` | `int` | No | Is the buyer a government entity? `1` = yes, `2` = no (default: `2`) |
 
+### Identification type fields
+
+| Type | Fields | XML output |
+|------|--------|------------|
+| `NipIdentification` | `nip: str` | `<NIP>` |
+| `EuVatIdentification` | `eu_country_code: str`, `eu_vat_number: str` | `<KodUE>` + `<NrVatUE>` |
+| `ForeignIdentification` | `country_code: Optional[str]`, `tax_id: str` | `<KodKraju>` (optional) + `<NrID>` |
+| `NoIdentification` | *(none)* | `<BrakID>1</BrakID>` |
+
 ---
 
 ## Address
diff --git a/src/ksef/models/invoice.py b/src/ksef/models/invoice.py
@@ -2,7 +2,7 @@
 from datetime import date, datetime
 from decimal import Decimal
 from enum import Enum
-from typing import Optional
+from typing import Optional, Union
 
 from pydantic import BaseModel
 
@@ -21,16 +21,34 @@ class IssuerIdentificationData(BaseModel):
     full_name: str
 
 
-class SubjectIdentificationData(BaseModel):
-    """
-    Subject identification data.
-
-    Corresponds to the field TPodmiot1/TPodmiot2 from the invoice XML schema.
-    """
+class NipIdentification(BaseModel):
+    """Polish NIP identification for Podmiot2."""
 
     nip: str
 
 
+class EuVatIdentification(BaseModel):
+    """EU VAT identification for Podmiot2."""
+
+    eu_country_code: str
+    eu_vat_number: str
+
+
+class ForeignIdentification(BaseModel):
+    """Non-EU foreign tax identification for Podmiot2."""
+
+    country_code: Optional[str] = None
+    tax_id: str
+
+
+class NoIdentification(BaseModel):
+    """No tax identification (individuals, B2C) for Podmiot2."""
+
+
+# Backwards-compatible alias
+SubjectIdentificationData = NipIdentification
+
+
 class Address(BaseModel):
     """Subject address data.
 
@@ -52,7 +70,10 @@ class Subject(BaseModel):
     Corresponds to the field TPodmiot2 from the invoice XML schema.
     """
 
-    identification_data: SubjectIdentificationData
+    identification_data: Union[
+        NipIdentification, EuVatIdentification, ForeignIdentification, NoIdentification
+    ]
+    name: Optional[str] = None
     address: Optional[Address] = None
     jst: int = 2
     gv: int = 2
diff --git a/src/ksef/xml_converters.py b/src/ksef/xml_converters.py
@@ -3,7 +3,13 @@
 from typing import Optional, cast
 from xml.etree import ElementTree
 
-from ksef.models.invoice import Invoice
+from ksef.models.invoice import (
+    EuVatIdentification,
+    ForeignIdentification,
+    Invoice,
+    NipIdentification,
+    NoIdentification,
+)
 
 # FA(3) schema namespace
 FA3_NAMESPACE = "http://crd.gov.pl/wzor/2025/06/25/13775/"
@@ -64,8 +70,29 @@ def _build_issuer(root: ElementTree.Element, invoice: Invoice) -> None:
 def _build_receiver(root: ElementTree.Element, invoice: Invoice) -> None:
     receiver = ElementTree.SubElement(root, "Podmiot2")
     receiver_id_data = ElementTree.SubElement(receiver, "DaneIdentyfikacyjne")
-    receiver_nip = ElementTree.SubElement(receiver_id_data, "NIP")
-    receiver_nip.text = invoice.recipient.identification_data.nip
+
+    id_data = invoice.recipient.identification_data
+    if isinstance(id_data, NipIdentification):
+        nip_el = ElementTree.SubElement(receiver_id_data, "NIP")
+        nip_el.text = id_data.nip
+    elif isinstance(id_data, EuVatIdentification):
+        kod_ue = ElementTree.SubElement(receiver_id_data, "KodUE")
+        kod_ue.text = id_data.eu_country_code
+        nr_vat = ElementTree.SubElement(receiver_id_data, "NrVatUE")
+        nr_vat.text = id_data.eu_vat_number
+    elif isinstance(id_data, ForeignIdentification):
+        if id_data.country_code is not None:
+            kod_kraju = ElementTree.SubElement(receiver_id_data, "KodKraju")
+            kod_kraju.text = id_data.country_code
+        nr_id = ElementTree.SubElement(receiver_id_data, "NrID")
+        nr_id.text = id_data.tax_id
+    elif isinstance(id_data, NoIdentification):
+        brak_id = ElementTree.SubElement(receiver_id_data, "BrakID")
+        brak_id.text = "1"
+
+    if invoice.recipient.name is not None:
+        nazwa = ElementTree.SubElement(receiver, "Nazwa")
+        nazwa.text = invoice.recipient.name
 
     if invoice.recipient.address is not None:
         addr = invoice.recipient.address
diff --git a/tests/xml_converters/test_convert_invoice_to_xml.py b/tests/xml_converters/test_convert_invoice_to_xml.py
@@ -7,11 +7,15 @@
 
 from ksef.models.invoice import (
     Address,
+    EuVatIdentification,
+    ForeignIdentification,
     Invoice,
     InvoiceData,
     InvoiceType,
     Issuer,
     IssuerIdentificationData,
+    NipIdentification,
+    NoIdentification,
     Subject,
     SubjectIdentificationData,
 )
@@ -156,3 +160,115 @@ def test_without_apartment_number() -> None:
     actual_content = convert_invoice_to_xml(invoice)
     assert_xml_equal(actual_content=actual_content, expected_content=expected_content)
     assert b"NrLokalu" not in actual_content
+
+
+def _make_invoice(recipient: Subject) -> Invoice:
+    """Build a minimal invoice with the given recipient."""
+    return Invoice(
+        issuer=Issuer(
+            identification_data=IssuerIdentificationData(
+                nip="1111111111", full_name="Example Company 1 Sp z o. o."
+            ),
+            email="example@example.com",
+            phone="+48 111111111",
+            address=Address(
+                country_code="PL",
+                city="Warszawa",
+                street="Kwiatowa",
+                house_number="1",
+                apartment_number="2",
+                postal_code="00-001",
+            ),
+        ),
+        recipient=recipient,
+        invoice_data=InvoiceData(
+            currency_code="PLN",
+            issue_date=date(2024, 1, 22),
+            issue_number="FA/1/2024",
+            sell_date=date(2024, 1, 1),
+            total_amount=Decimal("450.00"),
+            invoice_annotations=InvoiceAnnotations(
+                tax_settlement_on_payment=TaxSettlementOnPayment.REGULAR,
+                self_invoice=SelfInvoicing.NO,
+                reverse_charge=ReverseCharge.NO,
+                split_payment=SplitPayment.NO,
+                free_from_vat=FreeFromVat.NO,
+                intra_community_supply_of_new_transport_methods=IntraCommunitySupplyOfNewTransportMethods.NO,
+                simplified_procedure_by_second_tax_payer=SimplifiedProcedureBySecondTaxPayer.NO,
+                margin_procedure=MarginProcedure.NO,
+            ),
+            invoice_type=InvoiceType.REGULAR_VAT,
+            invoice_rows=InvoiceRows(
+                rows=[
+                    InvoiceRow(name="Example service 1", tax=23),
+                    InvoiceRow(name="Example service 2", tax=8),
+                ]
+            ),
+        ),
+        creation_datetime=datetime(2024, 1, 22, 10, 30, 0, tzinfo=timezone.utc),
+    )
+
+
+def test_recipient_eu_vat() -> None:
+    """Test EU company recipient produces KodUE + NrVatUE elements."""
+    invoice = _make_invoice(
+        Subject(
+            identification_data=EuVatIdentification(eu_country_code="DE", eu_vat_number="123456789")
+        )
+    )
+    xml = convert_invoice_to_xml(invoice)
+    soup = BeautifulSoup(xml, "xml")
+    id_data = soup.find("Podmiot2").find("DaneIdentyfikacyjne")
+    assert id_data.find("KodUE").text == "DE"
+    assert id_data.find("NrVatUE").text == "123456789"
+    assert id_data.find("NIP") is None
+
+
+def test_recipient_foreign_id() -> None:
+    """Test non-EU recipient with country code produces KodKraju + NrID."""
+    invoice = _make_invoice(
+        Subject(identification_data=ForeignIdentification(country_code="US", tax_id="EIN123"))
+    )
+    xml = convert_invoice_to_xml(invoice)
+    soup = BeautifulSoup(xml, "xml")
+    id_data = soup.find("Podmiot2").find("DaneIdentyfikacyjne")
+    assert id_data.find("KodKraju").text == "US"
+    assert id_data.find("NrID").text == "EIN123"
+    assert id_data.find("NIP") is None
+
+
+def test_recipient_foreign_id_without_country() -> None:
+    """Test non-EU recipient without country code produces only NrID."""
+    invoice = _make_invoice(Subject(identification_data=ForeignIdentification(tax_id="XYZ999")))
+    xml = convert_invoice_to_xml(invoice)
+    soup = BeautifulSoup(xml, "xml")
+    id_data = soup.find("Podmiot2").find("DaneIdentyfikacyjne")
+    assert id_data.find("NrID").text == "XYZ999"
+    assert id_data.find("KodKraju") is None
+
+
+def test_recipient_no_id() -> None:
+    """Test individual/B2C recipient produces BrakID and supports Nazwa."""
+    invoice = _make_invoice(Subject(identification_data=NoIdentification(), name="Jan Kowalski"))
+    xml = convert_invoice_to_xml(invoice)
+    soup = BeautifulSoup(xml, "xml")
+    podmiot2 = soup.find("Podmiot2")
+    id_data = podmiot2.find("DaneIdentyfikacyjne")
+    assert id_data.find("BrakID").text == "1"
+    assert id_data.find("NIP") is None
+    assert podmiot2.find("Nazwa").text == "Jan Kowalski"
+
+
+def test_recipient_with_name() -> None:
+    """Test NIP recipient with name produces both NIP and Nazwa."""
+    invoice = _make_invoice(
+        Subject(
+            identification_data=NipIdentification(nip="2222222222"),
+            name="Firma Testowa Sp. z o.o.",
+        )
+    )
+    xml = convert_invoice_to_xml(invoice)
+    soup = BeautifulSoup(xml, "xml")
+    podmiot2 = soup.find("Podmiot2")
+    assert podmiot2.find("DaneIdentyfikacyjne").find("NIP").text == "2222222222"
+    assert podmiot2.find("Nazwa").text == "Firma Testowa Sp. z o.o."
