GOBL ↔ KSeF Conversion

Bidirectional conversion between GOBL and the Polish FA_VAT XML format (KSeF).

Main Conversion Entrypoints

GOBL → KSeF:

• ksef.BuildFavat(env *gobl.Envelope) (*Invoice, error) - Converts a GOBL envelope to a KSeF FA_VAT invoice model
• (*Invoice).Bytes() ([]byte, error) - Returns the XML representation as bytes

KSeF → GOBL:

• ksef.ParseKSeF(xmlData []byte) (*gobl.Envelope, error) - Converts KSeF FA_VAT XML to a GOBL envelope

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.verifactu for Spain. Library would just be able to run tests in the first version.
3. Build a CLI (copy from gobl.cfdi and gobl.verifactu 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.

Testing

The test suite includes tests for both conversion directions and round-trip validation.

Running Tests

Run all tests:

go test ./test -v

Update golden files:

go test ./test --update -v

With XSD schema validation (requires libxml2):

# Using the helper script (sets LD_LIBRARY_PATH automatically)
./test/test.sh -v
./test/test.sh --update -v

# Or manually
LD_LIBRARY_PATH=/home/linuxbrew/.linuxbrew/opt/libxml2/lib:$LD_LIBRARY_PATH go test -tags xsdvalidate ./test -v

Test Data

GOBL → KSeF conversion:

• Input: GOBL JSON files in test/data/gobl.ksef/*.json
• Output: KSeF XML files in test/data/gobl.ksef/out/*.xml

KSeF → GOBL conversion:

• Input: KSeF XML files in test/data/ksef.gobl/*.xml
• Output: GOBL JSON files in test/data/ksef.gobl/out/*.json

Schema validation:

• Schema: FA3 XSD and dependencies in test/data/schema/

Unsupported fields

See unsupported-fields.md for the list of unsupported fields.

FA_VAT documentation

FA_VAT is the Polish electronic invoice format. The format uses XML.

• XML schema for V3 (description of fields is in Polish)
• Types definition (description of fields is in Polish) - we have to open it as raw, as the original link does not add newlines
• Complex types definition (description of fields is in Polish) - we have to open it as raw, as the original link does not add newlines

Parsing (KSeF → GOBL)

The parsing functionality converts KSeF FA_VAT XML documents back into GOBL format. The current implementation includes:

• Party conversion: Converts seller (Podmiot1), buyer (Podmiot2), and third parties (Podmiot3) to GOBL parties
• Invoice data: Parses invoice metadata including codes, dates, and currency
• Line items: Converts FA_VAT line items to GOBL invoice lines
• Payment terms: Extracts payment information and terms
• Rounding adjustments: Handles rounding differences to ensure totals match
• Round-trip validation: All conversions are validated through round-trip tests (GOBL → KSeF → GOBL)

Note: The parsing is functional but may not handle all edge cases. Some complex scenarios from the tax agency might require special handling, particularly invoices without line items, which would need synthetic lines created.

KSeF API

KSeF is the Polish system for submitting electronic invoices to the Polish authorities.

Useful links:

• National e-Invoice System - for details on system in general (English translation available - language picker is in the top right corner)
• KSeF Test Zone - as above, but for testing
• API documentation for the test environment (in Polish)

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) - sending a single document in each request.

Authentication

See authentication.md.