ksef

package module
v0.0.0-...-c985d1d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 19, 2024 License: Apache-2.0 Imports: 13 Imported by: 0

README

GOBL to KSeF Conversion

Convert GOBL to the Polish FA_VAT format and send to KSeF.

Copyright Invopop Ltd. 2023. Released publicly under the Apache License Version 2.0. For commercial licenses please contact the dev team at invopop. In order to accept contributions to this library we will require transferring copyrights to Invopop Ltd.

Project Development Objectives

The following list the steps to follow through on in order to accomplish the goal of using GOBL to submit electronic invoices to the Polish authorities:

  1. Add the PL (pl) tax regime to GOBL. Figure out local taxes, tax ID validation rules, and any "extensions" that may be required to be defined in GOBL, and send in a PR. For examples of existing regimes, see the regimes directory. Key Concerns:
    • Basic B2B invoices support.
    • Tax ID validation as per local rules.
    • Support for "simplified" invoices.
    • Requirements for credit-notes or "rectified" invoices and the correction options definition for the tax regime.
    • Any additional fields that need to be validated, like payment terms.
  2. Convert GOBL into FA_VAT format in library. A couple of good examples: gobl.cfdi for mexico and gobl.facturae for Spain. Library would just be able to run tests in the first version.
  3. Build a CLI (copy from gobl.cfdi and gobl.facture projects) to convert GOBL JSON documents into FA_VAT XML.
  4. Build a second part of this project that allows documents to be sent directly to the KSeF. A partial example of this can be found in the gobl.ticketbai project. It'd probably be useful to be able to upload via the CLI too.

KSeF API

Useful links:

KSeF provide three environments:

  1. Test Environment for application development with fictitious data.
  2. Pre-production "demo" area with production data, but not officially declared.
  3. Production

A translation of the Interface Specification 1.5 is available in the docs folder.

OpenAPI documentation is available for three specific interfaces:

  1. Batches (test openapi 'batch' spec) - for sending multiple documents at the same time.
  2. Common (test openapi 'common' spec) - general operations that don't require authentication.
  3. Interactive (test openapi 'online' spec)

Authentication

Authentication with KSeF appears to be done using digital certificates issued by trusted service providers approved by NCCert Poland.

There is an online process to register a company:

Once inside the test environment, you can create an Authorization token to use to make requests to the API.

Documentation

Overview

Package ksef implements the conversion from GOBL to FA_VAT XML

Package ksef implements the conversion from GOBL to FA_VAT XML

Index

Constants

View Source 
const (
	XSINamespace    = "http://www.w3.org/2001/XMLSchema-instance"
	XSDNamespace    = "http://www.w3.org/2001/XMLSchema"
	XMLNamespace    = "http://crd.gov.pl/wzor/2023/06/29/12648/"
	RootElementName = "Faktura"
)

Constants for KSeF XML

Variables

This section is empty.

Functions

This section is empty.

Types

type Address 

type Address struct {
	CountryCode string `xml:"KodKraju"`
	AddressL1   string `xml:"AdresL1"`
	AddressL2   string `xml:"AdresL2,omitempty"`
}

Address defines the XML structure for KSeF addresses

type AdvancePayment 

type AdvancePayment struct {
	PaymentAmount string `xml:"KwotaZaplatyCzesciowej,omitempty"`
	PaymentDate   string `xml:"DataZaplatyCzesciowej,omitempty"`
}

AdvancePayment defines the XML structure for KSeF advance payments

type Annotations 

type Annotations struct {
	CashAccounting                      int `xml:"P_16"`
	SelfBilling                         int `xml:"P_17"`
	ReverseCharge                       int `xml:"P_18"`
	SplitPaymentMechanism               int `xml:"P_18A"`
	NoTaxExemptGoods                    int `xml:"Zwolnienie>P_19N"`
	NoNewTransportIntraCommunitySupply  int `xml:"NoweSrodkiTransportu>P_22N"`
	SimplifiedProcedureBySecondTaxpayer int `xml:"P_23"`
	NoMarginProcedures                  int `xml:"PMarzy>P_PMarzyN"`
}

Annotations defines the XML structure for KSeF annotations

type BankAccount 

type BankAccount struct {
	AccountNumber         string `xml:"NrRB"`
	SWIFT                 string `xml:"SWIFT,omitempty"`
	BankSelfAccountMarker int    `xml:"RachunekWlasnyBanku,omitempty"` // enum - 1,2,3, not sure what exactly they mean
	BankName              string `xml:"NazwaBanku,omitempty"`
	AccountDescription    string `xml:"OpisRachunku,omitempty"`
}

BankAccount defines the XML structure for KSeF bank accounts

type Buyer 

type Buyer struct {
	NIP string `xml:"DaneIdentyfikacyjne>NIP,omitempty"`
	// or
	UECode      string `xml:"DaneIdentyfikacyjne>KodUE,omitempty"` //TODO
	UEVatNumber string `xml:"DaneIdentyfikacyjne>NrVatUE,omitempty"`
	// or
	CountryCode string `xml:"DaneIdentyfikacyjne>KodKraju,omitempty"`
	IDNumber    string `xml:"DaneIdentyfikacyjne>NrId,omitempty"`
	// or
	NoID int `xml:"DaneIdentyfikacyjne>BrakID,omitempty"`

	Name    string          `xml:"DaneIdentyfikacyjne>Nazwa,omitempty"`
	Address *Address        `xml:"Adres,omitempty"`
	Contact *ContactDetails `xml:"DaneKontaktowe,omitempty"`
}

Buyer defines the XML structure for KSeF buyer

func NewBuyer 

func NewBuyer(customer *org.Party) *Buyer

NewBuyer converts a GOBL Party into a KSeF buyer

type ContactDetails 

type ContactDetails struct {
	Phone string `xml:"Telefon,omitempty"`
	Email string `xml:"Email,omitempty"`
}

ContactDetails defines the XML structure for KSeF contact

type CorrectedInv 

type CorrectedInv struct {
	IssueDate           string `xml:"DataWystFaKorygowanej,omitempty"`
	SequentialNumber    string `xml:"NrFaKorygowanej,omitempty"`
	KsefNumberPresent   int    `xml:"NrKSeF,omitempty"`
	NoKsefNumberPresent int    `xml:"NrKSeFN,omitempty"`
	KsefNumber          string `xml:"NrKSeFFaKorygowanej,omitempty"`
}

CorrectedInv defines the XML structure for KSeF correction invoice

func NewCorrectedInv 

func NewCorrectedInv(prc *bill.Preceding) *CorrectedInv

NewCorrectedInv gets credit note data from GOBL invoice

type Discount 

type Discount struct {
	Conditions string `xml:"WarunkiSkonta,omitempty"`
	Amount     string `xml:"WysokoscSkonta,omitempty"`
}

Discount defines the XML structure for KSeF discount

type DueDate 

type DueDate struct {
	Date        string `xml:"Termin,omitempty"`
	Description string `xml:"TerminOpis,omitempty"`
}

DueDate defines the XML structure for KSeF due date

type FormCode 

type FormCode struct {
	SystemCode    string `xml:"kodSystemowy,attr"`
	SchemaVersion string `xml:"wersjaSchemy,attr"`
	FormCode      string `xml:",chardata"`
}

FormCode defines the XML structure for KSeF schema versioning 

type Header struct {
	FormCode     *FormCode `xml:"KodFormularza"`
	FormVariant  int       `xml:"WariantFormularza"`
	CreationDate string    `xml:"DataWytworzeniaFa"`
	SystemInfo   string    `xml:"SystemInfo,omitempty"`
}

Header defines the XML structure for KSeF header

func NewHeader 

func NewHeader(inv *bill.Invoice) *Header

NewHeader gets header data from GOBL invoice

type Inv 

type Inv struct {
	CurrencyCode                       string        `xml:"KodWaluty"`
	IssueDate                          string        `xml:"P_1"`
	IssuePlace                         string        `xml:"P_1M,omitempty"`
	SequentialNumber                   string        `xml:"P_2"`
	CompletionDate                     string        `xml:"P_6,omitempty"`
	StartDate                          string        `xml:"P_6_Od,omitempty"`
	EndDate                            string        `xml:"P_6_Do,omitempty"`
	StandardRateNetSale                string        `xml:"P_13_1,omitempty"`
	StandardRateTax                    string        `xml:"P_14_1,omitempty"`
	StandardRateTaxConvertedToPln      string        `xml:"P_14_1W,omitempty"`
	ReducedRateNetSale                 string        `xml:"P_13_2,omitempty"`
	ReducedRateTax                     string        `xml:"P_14_2,omitempty"`
	ReducedRateTaxConvertedToPln       string        `xml:"P_14_2W,omitempty"`
	SuperReducedRateNetSale            string        `xml:"P_13_3,omitempty"`
	SuperReducedRateTax                string        `xml:"P_14_3,omitempty"`
	SuperReducedRateTaxConvertedToPln  string        `xml:"P_14_3W,omitempty"`
	TaxiRateNetSale                    string        `xml:"P_13_4,omitempty"`
	TaxiRateTax                        string        `xml:"P_14_4,omitempty"`
	TaxiRateTaxConvertedToPln          string        `xml:"P_14_4W,omitempty"`
	SpecialProcedureNetSale            string        `xml:"P_13_5,omitempty"`
	SpecialProcedureTax                string        `xml:"P_14_5,omitempty"`
	ZeroTaxExceptIntraCommunityNetSale string        `xml:"P_13_6_1,omitempty"`
	IntraCommunityNetSale              string        `xml:"P_13_6_2,omitempty"`
	ExportNetSale                      string        `xml:"P_13_6_3,omitempty"`
	TaxExemptNetSale                   string        `xml:"P_13_7,omitempty"`
	InternationalNetSale               string        `xml:"P_13_8,omitempty"`
	OtherNetSale                       string        `xml:"P_13_9,omitempty"`
	EUServiceNetSale                   string        `xml:"P_13_10,omitempty"`
	MarginNetSale                      string        `xml:"P_13_11,omitempty"`
	TotalAmountReceivable              string        `xml:"P_15"`
	Annotations                        *Annotations  `xml:"Adnotacje"`
	InvoiceType                        string        `xml:"RodzajFaktury"`
	CorrectionReason                   string        `xml:"PrzyczynaKorekty,omitempty"`
	CorrectionType                     string        `xml:"TypKorekty,omitempty"`
	CorrectedInv                       *CorrectedInv `xml:"DaneFaKorygowanej,omitempty"`
	Lines                              []*Line       `xml:"FaWiersz"`
	Payment                            *Payment      `xml:"Platnosc"`
}

Inv defines the XML structure for KSeF invoice

func NewInv 

func NewInv(inv *bill.Invoice) *Inv

NewInv gets invoice data from GOBL invoice

type Invoice 

type Invoice struct {
	XMLName      xml.Name
	XSINamespace string  `xml:"xmlns:xsi,attr"`
	XSDNamespace string  `xml:"xmlns:xsd,attr"`
	XMLNamespace string  `xml:"xmlns,attr"`
	Header       *Header `xml:"Naglowek"`
	Seller       *Seller `xml:"Podmiot1"`
	Buyer        *Buyer  `xml:"Podmiot2"`
	ThirdParty   *Buyer  `xml:"Podmiot3,omitempty"` // third party
	Inv          *Inv    `xml:"Fa"`
}

Invoice is a pseudo-model for containing the XML document being created

func NewDocument 

func NewDocument(env *gobl.Envelope) (*Invoice, error)

NewDocument converts a GOBL envelope into a FA_VAT document

func (*Invoice) Bytes 

func (d *Invoice) Bytes() ([]byte, error)

Bytes returns the XML representation of the document in bytes

type Line 

type Line struct {
	LineNumber              int    `xml:"NrWierszaFa"`
	Name                    string `xml:"P_7,omitempty"`
	Measure                 string `xml:"P_8A,omitempty"`
	Quantity                string `xml:"P_8B,omitempty"`
	NetUnitPrice            string `xml:"P_9A,omitempty"`
	UnitDiscount            string `xml:"P_10,omitempty"`
	NetPriceTotal           string `xml:"P_11,omitempty"`
	TaxRate                 string `xml:"P_12,omitempty"`
	ExciseDuty              string `xml:"KwotaAkcyzy,omitempty"`
	SpecialGoodsCode        string `xml:"GTU,omitempty"` // values GTU_1 to GTU_13
	OSSTaxRate              string `xml:"P_12_XII,omitempty"`
	Attachment15GoodsMarker string `xml:"P_12_Zal_15,omitempty"`
	Procedure               string `xml:"Procedura,omitempty"`
	BeforeCorrectionMarker  string `xml:"StanPrzed,omitempty"`
}

Line defines the XML structure for KSeF item line

func NewLines 

func NewLines(lines []*bill.Line) []*Line

NewLines generates lines for the KSeF invoice

type Payment 

type Payment struct {
	PaidMarker             string            `xml:"Zaplacono,omitempty"`
	PaymentDate            string            `xml:"DataZaplaty,omitempty"`
	PartiallyPaidMarker    string            `xml:"ZnacznikZaplatyCzesciowej,omitempty"`
	AdvancePayments        []*AdvancePayment `xml:"ZaplataCzesciowa,omitempty"`
	DueDates               []*DueDate        `xml:"TerminPlatnosci,omitempty"`
	PaymentMean            string            `xml:"FormaPlatnosci,omitempty"`
	OtherPaymentMeanMarker string            `xml:"PlatnoscInna,omitempty"`
	OtherPaymentMean       string            `xml:"OpisPlatnosci,omitempty"`
	BankAccounts           []*BankAccount    `xml:"RachunekBankowy,omitempty"`
	FactorBankAccounts     []*BankAccount    `xml:"RachunekBankowyFaktora,omitempty"` // not sure if supported by gobl
	Discount               *Discount         `xml:"Skonto,omitempty"`                 // it's some special discount for early payments
}

Payment defines the XML structure for KSeF payment

func NewPayment 

func NewPayment(pay *bill.Payment, totals *bill.Totals) *Payment

NewPayment gets payment data from GOBL invoice

type Seller 

type Seller struct {
	NIP     string          `xml:"DaneIdentyfikacyjne>NIP"`
	Name    string          `xml:"DaneIdentyfikacyjne>Nazwa"`
	Address *Address        `xml:"Adres"`
	Contact *ContactDetails `xml:"DaneKontaktowe,omitempty"`
}

Seller defines the XML structure for KSeF seller

func NewSeller 

func NewSeller(supplier *org.Party) *Seller

NewSeller converts a GOBL Party into a KSeF seller

Source Files

View all Source files

Directories

Path Synopsis
api
Package api used for communication with the KSeF API
 Package api used for communication with the KSeF API
test
Package api_test provides tools for testing the api
 Package api_test provides tools for testing the api
cmd
gobl.ksef
Package main provides a CLI interface for the library
 Package main provides a CLI interface for the library
Package test provides tools for testing the library
 Package test provides tools for testing the library

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.