Documentation
¶
Index ¶
- Constants
- func JSON400ToString(errorResponse *ksefapi.ExceptionResponse) string
- type AdnotacjeXML
- type AdresXML
- type BlokDanychXML
- type Client
- type DaneFaKorygowanejXML
- type DaneKontaktoweXML
- type DodatkowyOpisXML
- type FaWierszXML
- type FaXML
- type FakturaXML
- type InformacjeXML
- type Invoice
- type InvoiceDetailContent
- type InvoiceDetails
- type InvoiceDetailsElement
- type InvoiceDetailsParty
- type InvoiceDetailsPayment
- type InvoicePage
- type InvoiceQuery
- type KodFormularzaXML
- type KolXML
- type MetaDanaXML
- type NaglowekXML
- type OkresFaXML
- type PlatnoscXML
- type Podmiot3XML
- type PodmiotXML
- type RachunekBankowyXML
- type RejestryXML
- type StopkaXML
- type SubjectType
- type TMetaDanaXML
- type TabelaXML
- type TerminPlatnosciXML
- type Tokens
- type WierszXML
- type ZalacznikXML
Constants ¶
const ( LevelWarn = slog.LevelWarn LevelInfo = slog.LevelInfo LevelDebug = slog.LevelDebug LevelTrace = slog.LevelDebug - 4 LevelSecret = slog.LevelDebug - 8 )
const FakturaXMLNamespace = "http://crd.gov.pl/wzor/2025/06/25/13775/"
FakturaXMLNamespace is the target namespace of the KSeF FA(3) schema. The date in the URL is part of the versioned namespace — a new major version of the schema (FA(4)) would have a different URL, requiring struct updates. FA(3) was introduced with mandatory KSeF in 2025 and is stable within this version.
Variables ¶
This section is empty.
Functions ¶
func JSON400ToString ¶
func JSON400ToString(errorResponse *ksefapi.ExceptionResponse) string
Types ¶
type AdnotacjeXML ¶ added in v0.0.4
type AdnotacjeXML struct {
MetodaKasowa string `xml:"P_16"` // metoda kasowa: 1=tak, 2=nie
Samofakturowanie string `xml:"P_17"` // samofakturowanie: 1=tak, 2=nie
OdwrotneObciazenie string `xml:"P_18"` // odwrotne obciążenie: 1=tak, 2=nie
PodzielonaPlatnosc string `xml:"P_18A"` // mechanizm podzielonej płatności: 1=tak, 2=nie
P_23 string `xml:"P_23"` // procedura uproszczona OSS/IOSS: 1=tak, 2=nie
}
AdnotacjeXML holds mandatory annotation flags. Values: "1" = tak, "2" = nie (chyba że opis mówi inaczej).
type AdresXML ¶ added in v0.0.4
type AdresXML struct {
KodKraju string `xml:"KodKraju"` // kod kraju, np. "PL"
AdresL1 string `xml:"AdresL1"` // pierwsza linia adresu
AdresL2 string `xml:"AdresL2"` // druga linia adresu (opcjonalna)
GLN string `xml:"GLN"` // Global Location Number (opcjonalne)
}
AdresXML holds address lines.
type BlokDanychXML ¶ added in v0.0.4
type BlokDanychXML struct {
MetaDane []MetaDanaXML `xml:"MetaDane"` // ogólne metadane bloku
Tabele []TabelaXML `xml:"Tabela"`
}
BlokDanychXML is a data block in an attachment.
type Client ¶
type Client interface {
Login(ctx context.Context, nip string, token string) (*Tokens, error)
GetInvoices(ctx context.Context, query InvoiceQuery, page InvoicePage) ([]Invoice, error)
GetInvoiceDetails(ctx context.Context, invoiceNumber string) (*InvoiceDetails, error)
GetInvoiceDetailsRaw(ctx context.Context, invoiceNumber string) ([]byte, error)
RefreshTokens(ctx context.Context) (*Tokens, error)
SetTokens(tokens *Tokens)
GetTokens() *Tokens
}
type DaneFaKorygowanejXML ¶ added in v0.0.4
type DaneFaKorygowanejXML struct {
DataWyst string `xml:"DataWystFaKorygowanej"`
NrFaKorygowanej string `xml:"NrFaKorygowanej"`
NrKSeF string `xml:"NrKSeF"` // "1" jeśli faktura korygowana ma nr KSeF
NrKSeFFaKorygowanej string `xml:"NrKSeFFaKorygowanej"` // nr KSeF faktury korygowanej
}
DaneFaKorygowanejXML is required when RodzajFaktury = "KOR".
type DaneKontaktoweXML ¶ added in v0.0.4
DaneKontaktoweXML holds optional contact data for Podmiot2.
type DodatkowyOpisXML ¶ added in v0.0.4
type DodatkowyOpisXML struct {
NrWiersza string `xml:"NrWiersza"` // opcjonalne; numer pozycji, której dotyczy opis
Klucz string `xml:"Klucz"`
Wartosc string `xml:"Wartosc"`
}
DodatkowyOpisXML holds optional key-value metadata at invoice or line level.
type FaWierszXML ¶ added in v0.0.4
type FaWierszXML struct {
Nr string `xml:"NrWierszaFa"`
DataPoz string `xml:"P_6A"` // opcjonalne; data dostawy dla tej pozycji
Nazwa string `xml:"P_7"` // nazwa towaru lub usługi
Jm string `xml:"P_8A"` // jednostka miary
Ilosc string `xml:"P_8B"` // ilość (quantity)
Cena string `xml:"P_9A"` // cena jednostkowa netto
CenaB string `xml:"P_9B"` // cena jednostkowa brutto (art. 106e ust. 7); opcjonalne
Rabat string `xml:"P_10"` // opust/obniżka ceny; opcjonalne
Netto string `xml:"P_11"` // wartość sprzedaży netto
Brutto string `xml:"P_11A"` // wartość sprzedaży brutto (art. 106e ust. 7); opcjonalne
Vat string `xml:"P_11Vat"` // kwota podatku (art. 106e ust. 10); opcjonalne
StVAT string `xml:"P_12"` // stawka podatku: 23, 8, 5, 0, ZW, NP, OO
GTU string `xml:"GTU"` // oznaczenie GTU (Grupy Towarowo-Usługowe); opcjonalne
}
FaWierszXML represents a single invoice line item. Note on P_8B / P_9A: XSD defines P_8B as "ilość" (quantity) and P_9A as "cena jednostkowa netto" (unit price). In practice some issuers use them in reversed order — verify with P_11 = P_8B * P_9A.
type FaXML ¶ added in v0.0.4
type FaXML struct {
KodWaluty string `xml:"KodWaluty"` // waluta, np. "PLN"
DataWyst string `xml:"P_1"` // data wystawienia faktury
MiejsceWyst string `xml:"P_1M"` // miejsce wystawienia (opcjonalne)
NumerFaktury string `xml:"P_2"` // numer faktury
DataDostawy string `xml:"P_6"` // data dostawy/wykonania usługi (wspólna dla wszystkich pozycji); alternatywa dla OkresFa
OkresFa OkresFaXML `xml:"OkresFa"` // okres rozliczeniowy; alternatywa dla P_6
// Kwoty w podziale na stawki VAT — wartości ujemne oznaczają korektę.
KwotaNetto23 string `xml:"P_13_1"` // netto 23% (lub 22%)
KwotaVAT23 string `xml:"P_14_1"` // VAT 23% (lub 22%)
KwotaVAT23W string `xml:"P_14_1W"` // VAT 23% w złotych gdy faktura w walucie obcej (opcjonalne)
KwotaNetto8 string `xml:"P_13_2"` // netto 8% (lub 7%); opcjonalne
KwotaVAT8 string `xml:"P_14_2"` // VAT 8% (lub 7%); opcjonalne
KwotaVAT8W string `xml:"P_14_2W"` // VAT 8% w złotych gdy faktura w walucie obcej; opcjonalne
KwotaNetto5 string `xml:"P_13_3"` // netto 5%; opcjonalne
KwotaVAT5 string `xml:"P_14_3"` // VAT 5%; opcjonalne
KwotaVAT5W string `xml:"P_14_3W"` // VAT 5% w złotych gdy faktura w walucie obcej; opcjonalne
KwotaNetto0 string `xml:"P_13_5"` // netto 0% (krajowe, bez WDT i eksportu); opcjonalne
KwotaNettoWDT string `xml:"P_13_6"` // netto 0% WDT; opcjonalne
KwotaNettoEKS string `xml:"P_13_7"` // netto 0% eksport; opcjonalne
KwotaZW string `xml:"P_13_8"` // sprzedaż zwolniona; opcjonalne
KwotaPozaTer string `xml:"P_13_9"` // poza terytorium kraju; opcjonalne
KwotaOdwObci string `xml:"P_13_11"` // odwrotne obciążenie; opcjonalne
KwotaBrutto string `xml:"P_15"` // łączna kwota należności (brutto)
Adnotacje AdnotacjeXML `xml:"Adnotacje"`
RodzajFaktury string `xml:"RodzajFaktury"` // VAT, KOR, ZAL, ROZ, UPR, KOR_ZAL, KOR_ROZ
DaneFaKorygowanej *DaneFaKorygowanejXML `xml:"DaneFaKorygowanej"` // wymagane gdy RodzajFaktury=KOR
OkresFaKorygowanej string `xml:"OkresFaKorygowanej"` // okres korygowanej faktury (opcjonalne)
DodatkowyOpis []DodatkowyOpisXML `xml:"DodatkowyOpis"` // dowolne pary klucz-wartość
Wiersze []FaWierszXML `xml:"FaWiersz"`
Platnosc PlatnoscXML `xml:"Platnosc"`
}
FaXML is the main invoice body element.
type FakturaXML ¶ added in v0.0.4
type FakturaXML struct {
XMLName xml.Name `xml:"Faktura"`
Naglowek NaglowekXML `xml:"Naglowek"`
Podmiot1 PodmiotXML `xml:"Podmiot1"`
Podmiot2 PodmiotXML `xml:"Podmiot2"`
Podmiot3 []Podmiot3XML `xml:"Podmiot3"` // podmioty trzecie, opcjonalne
Fa FaXML `xml:"Fa"`
Stopka StopkaXML `xml:"Stopka"`
Zalacznik *ZalacznikXML `xml:"Zalacznik"` // opcjonalne załączniki z danymi technicznymi
}
FakturaXML is the root element of a KSeF FA(3) e-invoice. Schema: https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd
type InformacjeXML ¶ added in v0.0.4
type InformacjeXML struct {
StopkaFaktury string `xml:"StopkaFaktury"`
}
InformacjeXML holds a single footer text block.
type Invoice ¶
type Invoice struct {
GrossAmount float64 `json:"gross_amount"`
NetAmount float64 `json:"net_amount"`
InvoiceNumber string `json:"invoice_number"`
KsefNumber string `json:"ksef_number"`
PermanentStorageDate time.Time `json:"permanent_storage_date"`
SellerNIP string `json:"seller_nip"`
SellerName string `json:"seller_name"`
}
type InvoiceDetailContent ¶ added in v0.0.4
type InvoiceDetailContent struct {
Netto0 float64 `json:"netto0"`
Vat0 float64 `json:"vat0"`
Netto5 float64 `json:"netto5"`
Vat5 float64 `json:"vat5"`
Netto8 float64 `json:"netto8"`
Vat8 float64 `json:"vat8"`
NettoExempt float64 `json:"nettoExempt"`
Netto23 float64 `json:"netto23"`
Vat23 float64 `json:"vat23"`
GrossAmount float64 `json:"grossAmount"`
DateOfSale string `json:"dateOfSale"`
Items []InvoiceDetailsElement `json:"elements"`
Payment InvoiceDetailsPayment `json:"payment"`
}
type InvoiceDetails ¶ added in v0.0.4
type InvoiceDetails struct {
Seller InvoiceDetailsParty `json:"seller"`
Buyer InvoiceDetailsParty `json:"buyer"`
InvoiceNumber string `json:"invoiceNumber"`
KsefNumber string `json:"ksefNumber"`
DateOfIssue string `json:"dateOfIssue"`
Content InvoiceDetailContent `json:"content"`
}
type InvoiceDetailsElement ¶ added in v0.0.4
type InvoiceDetailsElement struct {
OrderNumber string `json:"orderNumber"`
Description string `json:"description"`
Unit string `json:"unit"`
Quantity float64 `json:"quantity"`
NetPrice float64 `json:"netPrice"`
GrossPrice float64 `json:"grossPrice"`
NetAmount float64 `json:"netAmount"`
GrossAmount float64 `json:"grossAmount"`
VatAmount float64 `json:"vatAmount"`
VatRate float64 `json:"vatRate"`
}
type InvoiceDetailsParty ¶ added in v0.0.4
type InvoiceDetailsPayment ¶ added in v0.0.4
type InvoicePage ¶
type InvoiceQuery ¶
type InvoiceQuery struct {
From time.Time
To time.Time
SubjectType SubjectType
}
type KodFormularzaXML ¶ added in v0.0.4
type KodFormularzaXML struct {
KodSystemowy string `xml:"kodSystemowy,attr"` // np. "FA (3)"
WersjaSchemy string `xml:"wersjaSchemy,attr"` // np. "1-0E"
Value string `xml:",chardata"` // np. "FA"
}
KodFormularzaXML contains the form code with schema version attributes.
type KolXML ¶ added in v0.0.4
type KolXML struct {
Typ string `xml:"Typ,attr"` // typ: txt, dec, date
NKom string `xml:"NKom"` // nagłówek kolumny
}
KolXML describes a column in an attachment table.
type MetaDanaXML ¶ added in v0.0.4
MetaDanaXML holds a single key-value metadata entry for an attachment block.
type NaglowekXML ¶ added in v0.0.4
type NaglowekXML struct {
KodFormularza KodFormularzaXML `xml:"KodFormularza"`
WariantFormularza string `xml:"WariantFormularza"` // zawsze "3"
DataWytworzeniaFa string `xml:"DataWytworzeniaFa"` // datetime wytworzenia pliku
SystemInfo string `xml:"SystemInfo"` // opcjonalne; nazwa systemu wystawiającego
}
NaglowekXML is the invoice header.
type OkresFaXML ¶ added in v0.0.4
type OkresFaXML struct {
Od string `xml:"P_6_Od"` // data początkowa okresu
Do string `xml:"P_6_Do"` // data końcowa okresu
}
OkresFaXML holds the billing period when the invoice covers a date range.
type PlatnoscXML ¶ added in v0.0.4
type PlatnoscXML struct {
TerminPlatnosci TerminPlatnosciXML `xml:"TerminPlatnosci"`
// FormaPlatnosci: 1=gotówka 2=karta 3=bon 4=czek 5=kredyt 6=przelew 7=mobilna
FormaPlatnosci string `xml:"FormaPlatnosci"`
RachunekBankowy RachunekBankowyXML `xml:"RachunekBankowy"`
}
PlatnoscXML holds payment terms and method.
type Podmiot3XML ¶ added in v0.0.4
type Podmiot3XML struct {
NIP string `xml:"DaneIdentyfikacyjne>NIP"`
Nazwa string `xml:"DaneIdentyfikacyjne>Nazwa"`
Adres AdresXML `xml:"Adres"`
Rola string `xml:"Rola"` // rola podmiotu
Rola2 string `xml:"Rola2"` // dodatkowa rola
IDNabyw string `xml:"IDNabyw"` // identyfikator w systemie nabywcy
}
Podmiot3XML represents optional third parties (np. faktorant, odbiorca).
type PodmiotXML ¶ added in v0.0.4
type PodmiotXML struct {
PrefiksPodatnika string `xml:"PrefiksPodatnika"` // opcjonalne; np. "PL"
NIP string `xml:"DaneIdentyfikacyjne>NIP"`
KodUE string `xml:"DaneIdentyfikacyjne>KodUE"` // alternatywa NIP: kod UE
NrVatUE string `xml:"DaneIdentyfikacyjne>NrVatUE"` // alternatywa NIP: nr VAT UE
BrakID string `xml:"DaneIdentyfikacyjne>BrakID"` // "1" gdy podmiot bez NIP
Nazwa string `xml:"DaneIdentyfikacyjne>Nazwa"`
Adres AdresXML `xml:"Adres"`
DaneKontaktowe DaneKontaktoweXML `xml:"DaneKontaktowe"` // opcjonalne; tylko Podmiot2
JST string `xml:"JST"` // Jednostka sektora finansów: 1=tak, 2=nie
GV string `xml:"GV"` // Grupa VAT: 1=tak, 2=nie
}
PodmiotXML represents Podmiot1 (sprzedawca) or Podmiot2 (nabywca). Pole NIP jest obowiązkowe; inne pola identyfikacyjne (KodUE/NrVatUE/BrakID) są alternatywami dla NIP w przypadkach szczególnych — tu uwzględniony wyłącznie NIP.
type RachunekBankowyXML ¶ added in v0.0.4
type RachunekBankowyXML struct {
NrRB string `xml:"NrRB"`
SWIFT string `xml:"SWIFT"` // opcjonalne
NazwaBanku string `xml:"NazwaBanku"` // opcjonalne
OpisRachunku string `xml:"OpisRachunku"` // opcjonalne
}
RachunekBankowyXML holds bank account details.
type RejestryXML ¶ added in v0.0.4
type RejestryXML struct {
PelnaNazwa string `xml:"PelnaNazwa"` // pełna nazwa (opcjonalne)
KRS string `xml:"KRS"` // numer KRS (opcjonalne)
REGON string `xml:"REGON"` // numer REGON (opcjonalne)
}
RejestryXML holds company registry data.
type StopkaXML ¶ added in v0.0.4
type StopkaXML struct {
Informacje []InformacjeXML `xml:"Informacje"` // może być kilka bloków tekstu
Rejestry RejestryXML `xml:"Rejestry"`
}
StopkaXML is the invoice footer.
type SubjectType ¶
type SubjectType string
const ( Subject1 SubjectType = "Subject1" Subject2 SubjectType = "Subject2" Subject3 SubjectType = "Subject3" SubjectAuthorized SubjectType = "SubjectAuthorized" )
type TMetaDanaXML ¶ added in v0.0.4
TMetaDanaXML holds a single key-value metadata entry for a table.
type TabelaXML ¶ added in v0.0.4
type TabelaXML struct {
TMetaDane []TMetaDanaXML `xml:"TMetaDane"` // metadane tabeli (klucz-wartość)
Opis string `xml:"Opis"` // opis tabeli
TNaglowek struct {
Kol []KolXML `xml:"Kol"`
} `xml:"TNaglowek"`
Wiersze []WierszXML `xml:"Wiersz"`
}
TabelaXML is a structured table in an attachment block.
type TerminPlatnosciXML ¶ added in v0.0.4
type TerminPlatnosciXML struct {
Termin string `xml:"Termin"`
}
TerminPlatnosciXML holds a single payment deadline.
type WierszXML ¶ added in v0.0.4
type WierszXML struct {
Komorki []string `xml:"WKom"` // wartości kolejnych kolumn
}
WierszXML is a data row in an attachment table.
type ZalacznikXML ¶ added in v0.0.4
type ZalacznikXML struct {
BlokDanych BlokDanychXML `xml:"BlokDanych"`
}
ZalacznikXML holds optional structured attachments (e.g. meter readings, usage tables).