Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pprzetacznik/ksef-utils
KSeF Python client for creating invoices
https://github.com/pprzetacznik/ksef-utils
invoicing ksef openapi python
Last synced: 7 days ago
JSON representation
KSeF Python client for creating invoices
- Host: GitHub
- URL: https://github.com/pprzetacznik/ksef-utils
- Owner: pprzetacznik
- License: other
- Created: 2023-11-26T22:57:19.000Z (12 months ago)
- Default Branch: master
- Last Pushed: 2024-10-27T22:18:54.000Z (19 days ago)
- Last Synced: 2024-10-28T01:34:24.884Z (19 days ago)
- Topics: invoicing, ksef, openapi, python
- Language: Python
- Homepage: https://pypi.org/project/ksef-utils/
- Size: 59.6 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# KSeF utils
[](https://github.com/pprzetacznik/ksef-utils/actions/workflows/release.yml)
[](https://github.com/pprzetacznik/ksef-utils/actions/workflows/test.yml)
[](https://pypi.org/project/ksef-utils/)
[](https://pypi.org/project/ksef-utils/)
[](https://ksef-utils.readthedocs.io/en/latest/?badge=latest)
This project contains Python utilities and example requests that can be helpful when integrating with Polish central invoicing system called [Krajowy System e-Faktur (KSeF)](https://www.podatki.gov.pl/ksef/).
## Installation
### Creating python virtual environment
See [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/) documentation.
```Bash
$ mkvirtualenv ksef
$ workon ksef
(ksef) $
```
### Installing package from source
```Bash
(ksef) $ git clone https://github.com/pprzetacznik/ksef-utils.git
(ksef) $ cd ksef-utils
(ksef) $ pip install -e .
```
### Installing package from PyPI
```Bash
(ksef) $ pip install ksef-utils
```
## Run tests
### Set up secrets
Log in to https://ksef-test.mf.gov.pl/web/ and generate your individual `KSEF_TOKEN`.
```Bash
#!/bin/bash
export KSEF_TOKEN="..."
export KSEF_ENV="test"
export KSEF_NIP="..."
export KSEF_SIGN_CERT_PATH="cert.pem"
export KSEF_SIGN_KEY_PATH="privkey.pem"
export KSEF_SIGN_CA_PATH="cert.pem"
```
### Generate test cert
```Bash
KSEF_NIP=${KSEF_NIP:-2222222222}
KSEF_SUBJECT="/CN=John Doe/SN=Doe/GN=John/O=My Corp/C=PL/L=Lesser Voivodeship/serialNumber=NIP-${KSEF_NIP}/description=John Doe NIP-${KSEF_NIP}"
openssl req -x509 \
-nodes \
-subj "${KSEF_SUBJECT}" \
-days 365 \
-newkey rsa \
-keyout $KSEF_SIGN_KEY_PATH \
-out $KSEF_SIGN_CERT_PATH
```
### Run pytest framework
```Bash
(ksef) $ pip install -r requirements.txt
(ksef) $ pytest -svvv
```
### Markers
Run all e2e/functional/current tests
```
(ksef) $ pytest -svvv tests/test_ksef.py -m "e2e and not ignore"
(ksef) $ pytest -svvv tests/test_ksef.py -m "functional and not ignore"
(ksef) $ pytest -svvv tests/test_ksef.py -m "current and not ignore"
(ksef) $ ./run_tests.sh
(ksef) $ TESTS_MARKERS="init_signed and functional and not ignore" ./run_tests.sh
```
## Example
See [tests/test_e2e.py](tests/test_e2e.py) for detailed examples of usage.
```Python
from ksef_utils.server import KSEFServer, KSEFService
from ksef_utils.config import TestConfig, DemoConfig, ProdConfig
config = TestConfig()
server = KSEFServer(config)
service = KSEFService(service)
invoice_data = {
# ...
# see tests/conftest.py for example json invoice
}
session_token = service.init_signed()
response_send_invoice = service.send_invoice(**invoice_data)
```
## Using cli utilities
```
(ksef) $ python -m ksef_utils keygen --identifier 1111111111 --identifier_type NIP --working_directory .
(ksef) $ pip install .
(ksef) $ which ksef-utils
(...)/.envs/bin/ksef-utils
(ksef) $ ksef-utils keygen --identifier 1111111111 --identifier_type PESEL --working_directory .
```
## OpenAPI
```
/openapi/gtw/svc/api/KSeF-common.yaml
/openapi/gtw/svc/api/KSeF-batch.yaml
/openapi/gtw/svc/api/KSeF-online.yaml
```
## Publish new release
```Bash
$ git tag v1.0
$ git push origin v1.0
```
## Building documentation
```Bash
(ksef) $ sphinx-build -M html docs docs_build
```
## KSEF references
* https://www.podatki.gov.pl/ksef/
* https://ksef-test.mf.gov.pl/web/
* https://www.youtube.com/watch?v=dnBGO6IPtzA
## Contributing
* https://www.conventionalcommits.org/en/v1.0.0/