invopop/gobl.ksef

Convert GOBL to the Polish FA_VAT format and send to KSeF

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:

• National e-Invoice System - for details on system in general.
• KSeF Test Zone

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:

• Test Company login
• Generate a fake NIP (tax ID)

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