Extra KSeF Fields (Advanced)

Additional Structured Descriptions - DodatkowyOpis - (Header +Lines)

You may want to add additional descriptions, with a specific structure or signification.

Below the method:

Is included in Billit Json on header level, stored in KSeF XML on header level
Refers to :
- an Invoice line
- the invoice header
Multiple occurrencies are possible, even for one invoice line
Billit Added a Sequence Numbering:
- e.g. DodatkowyOpis1, DodatkowyOpis2 : this for verification of the coherence by Billit.
- This sequence number is mandatory. If not used, invoices will go in error.
Data elements:

Description	Billit API Header Custom Field	Max length	Mandatory
Key : the signification of your field	Faktura.FA.DodatkowyOpis1.Klucz	256	Mandatory
The value / (content of the field)	Faktura.FA.DodatkowyOpis1.Wartosc	256	Mandatory
Link to invoice line number. When added : linked to a line. When not present : linked to the header	Faktura.FA.DodatkowyOpis2.NrWiersza		Optional

Example:

    "CustomFields": 
    {
        "Faktura.FA.DodatkowyOpis1.NrWiersza": "2", // Link to invoice line number  
        "Faktura.FA.DodatkowyOpis1.Klucz": "Numer awiza",  //key
        "Faktura.FA.DodatkowyOpis1.Wartosc": "SIRL12040454042",  // the value - content for that key
        "Faktura.FA.DodatkowyOpis2.NrWiersza": "2",  // second reference linked to the line 
        "Faktura.FA.DodatkowyOpis2.Klucz": "Numer pozycji zamówienia klienta",
        "Faktura.FA.DodatkowyOpis2.Wartosc": "001000",
        "Faktura.FA.DodatkowyOpis3.NrWiersza": "3",
        "Faktura.FA.DodatkowyOpis3.Klucz": "Numer pozycji zamówienia klienta",
        "Faktura.FA.DodatkowyOpis3.Wartosc": "002000"
    },

	"CustomFields": {
		"Faktura.FA.DodatkowyOpis1.Klucz": "BDO",     
		"Faktura.FA.DodatkowyOpis1.Wartosc": "000040999", //Header value
		"Faktura.FA.DodatkowyOpis2.Klucz": "TEST1",
		"Faktura.FA.DodatkowyOpis2.Wartosc": "0000565", //Header value
    "Faktura.FA.DodatkowyOpis3.Klucz": "TEST2",
		"Faktura.FA.DodatkowyOpis3.Wartosc": "0000569",
		"Faktura.FA.DodatkowyOpis3.NrWiersza": "1",  //For Line 1
    "Faktura.FA.DodatkowyOpis4.Klucz": "TEST3",
		"Faktura.FA.DodatkowyOpis4.Wartosc": "0000560",
		"Faktura.FA.DodatkowyOpis4.NrWiersza": "1", //For Line 1
    "Faktura.FA.DodatkowyOpis5.Klucz": "TEST4",
		"Faktura.FA.DodatkowyOpis5.Wartosc": "0000561",
		"Faktura.FA.DodatkowyOpis5.NrWiersza": "2", //For Line 2
    "Faktura.FA.DodatkowyOpis6.Klucz": "TEST5",
		"Faktura.FA.DodatkowyOpis6.Wartosc": "0000562",
		"Faktura.FA.DodatkowyOpis6.NrWiersza": "2" //For Line 2
    "Faktura.FA.DodatkowyOpis7.Klucz": "Sample Key",     
		"Faktura.FA.DodatkowyOpis7.Wartosc": "000050103" //Header value
	},

Alternative Payment Term Information (Header)

The due date is filled in the normal KSeF area : Platnosc / TerminPlatnosci / Termin.

There are legal scenario's where the althernative TermOpis can be used. So on request and via API, this specific information can be included.

Example:

    "CustomFields": 
    {
        "Faktura.Fa.Platnosc.TerminPlatnosci.TerminOpis.Ilosc" : "14", // this is the quantity
        "Faktura.Fa.Platnosc.TerminPlatnosci.TerminOpis.Jednostka" : "day", // this I a unit as free text
        "Faktura.Fa.Platnosc.TerminPlatnosci.TerminOpis.ZdarzeniePoczatkowe" : "Payment deadline description"  // free text, maximum 256 characters

    },

    <Platnosc>
      <TerminPlatnosci>
        <Termin>2026-04-17</Termin>
        <TerminOpis>
          <Ilosc>14</Ilosc>
          <Jednostka>day</Jednostka>
          <ZdarzeniePoczatkowe>Payment deadline description</ZdarzeniePoczatkowe>
        </TerminOpis>
      </TerminPlatnosci>
    </Platnosc>

Add Payment Method (Header)

Payment methods exist in KSeF to compare with Peppol PaymentMeanscode. This appears in the segment Platnosc, field FormaPlatnosci. Following information: • Not a mandatory field • KSeF verification : must be in a list of allowed values

Table with the values:

Value	Description	Payment Method Description at Billit
1	Gotówka	Cash
2	Karta	Bancontact
3	Bon
4	Czek
5	Kredyt	Visa
6	Przelew	Wired (= bank transfer, is most common value)
7	Mobilna

Example:

    "CustomFields": 
    {
        "Faktura.Fa.Platnosc.FormaPlatnosci" : "6" 
    },

Delivery Address in Transport Segment (Header)

In the transport segment, Billit supports a number of fields via custom Fields on header level.

Billit	Descripton	Mandatory
Faktura.Fa.WarunkiTransakcji.Transport.RodzajTransportu	Type of transport : set value from list	yes
Faktura.Fa.WarunkiTransakcji.Transport.OpisLadunku	Type of cargo : set value from list	yes
Faktura.Fa.WarunkiTransakcji.Transport.WysylkaDo.KodKraju	Country code	yes
Faktura.Fa.WarunkiTransakcji.Transport.WysylkaDo.AdresL1	Street and street number	yes
Faktura .Fa.WarunkiTransakcji.Transport.WysylkaDo.AdresL2"	Zip and City	yes

Example below.

    "CustomFields": 
    {
               "Faktura.Fa.WarunkiTransakcji.Transport.RodzajTransportu" : "3", // TransportType 3: Road transport (most common type).  This is from a list (value 1 to 8)
        "Faktura.Fa.WarunkiTransakcji.Transport.OpisLadunku" : "13", // Cargo type 13: Pallet.  This is from a list (value 1 to 20)
        // "Faktura.Fa.WarunkiTransakcji.Transport.JednostkaOpakowania" : "1 cardboard box/40 pieces", // Packing unit
        "Faktura.Fa.WarunkiTransakcji.Transport.WysylkaDo.KodKraju" : "PL",  //Country
        "Faktura.Fa.WarunkiTransakcji.Transport.WysylkaDo.AdresL1" : "ul. Sadowa 1 lok. 3",  //Street and number
        "Faktura .Fa.WarunkiTransakcji.Transport.WysylkaDo.AdresL2" : "00-002 Kraków"  // Zip and City
    },

 <WarunkiTransakcji>
      <Zamowienia />
      <Transport>
        <RodzajTransportu>3</RodzajTransportu>
        <OpisLadunku>13</OpisLadunku>
        <WysylkaDo>
          <KodKraju>PL</KodKraju>
          <AdresL1>ul. Sadowa 1 lok. 3</AdresL1>
        </WysylkaDo>
      </Transport>
    </WarunkiTransakcji>

List of other values for TransportTypes: See KSeF documentation.