# KSeF utils
[![ksef-utils Release](https://github.com/pprzetacznik/ksef-utils/actions/workflows/release.yml/badge.svg)](https://github.com/pprzetacznik/ksef-utils/actions/workflows/release.yml)
[![ksef-utils Test](https://github.com/pprzetacznik/ksef-utils/actions/workflows/test.yml/badge.svg)](https://github.com/pprzetacznik/ksef-utils/actions/workflows/test.yml)
[![PyPI version](https://badge.fury.io/py/ksef-utils.svg)](https://pypi.org/project/ksef-utils/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ksef-utils)](https://pypi.org/project/ksef-utils/)
[![Documentation Status](https://readthedocs.org/projects/ksef-utils/badge/?version=latest)](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 --identifier 1111111111 --identifier_type NIP --working_directory .
(ksef) $ pip install .
(ksef) $ which ksef-utils
(...)/.envs/bin/ksef-utils
(ksef) $ ksef-utils --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/
Raw data
{
"_id": null,
"home_page": "https://github.com/pprzetacznik/ksef-utils",
"name": "ksef-utils",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "invoices,ksef",
"author": "Piotr Przetacznik",
"author_email": "\"piotr.przetacznik+ksef@gmail.com\",",
"download_url": "https://files.pythonhosted.org/packages/81/77/b457f425047a2befa6f589086456558e9cf98d138613dc41efc84eba6d47/ksef-utils-1.3.tar.gz",
"platform": null,
"description": "# KSeF utils\n\n[![ksef-utils Release](https://github.com/pprzetacznik/ksef-utils/actions/workflows/release.yml/badge.svg)](https://github.com/pprzetacznik/ksef-utils/actions/workflows/release.yml)\n[![ksef-utils Test](https://github.com/pprzetacznik/ksef-utils/actions/workflows/test.yml/badge.svg)](https://github.com/pprzetacznik/ksef-utils/actions/workflows/test.yml)\n[![PyPI version](https://badge.fury.io/py/ksef-utils.svg)](https://pypi.org/project/ksef-utils/)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ksef-utils)](https://pypi.org/project/ksef-utils/)\n[![Documentation Status](https://readthedocs.org/projects/ksef-utils/badge/?version=latest)](https://ksef-utils.readthedocs.io/en/latest/?badge=latest)\n\nThis 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/).\n\n## Installation\n\n### Creating python virtual environment\n\nSee [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/) documentation.\n\n```Bash\n$ mkvirtualenv ksef\n$ workon ksef\n(ksef) $\n```\n\n### Installing package from source\n\n```Bash\n(ksef) $ git clone https://github.com/pprzetacznik/ksef-utils.git\n(ksef) $ cd ksef-utils\n(ksef) $ pip install -e .\n```\n\n### Installing package from PyPI\n\n```Bash\n(ksef) $ pip install ksef-utils\n```\n\n## Run tests\n\n### Set up secrets\n\nLog in to https://ksef-test.mf.gov.pl/web/ and generate your individual `KSEF_TOKEN`.\n\n```Bash\n#!/bin/bash\n\nexport KSEF_TOKEN=\"...\"\nexport KSEF_ENV=\"test\"\nexport KSEF_NIP=\"...\"\nexport KSEF_SIGN_CERT_PATH=\"cert.pem\"\nexport KSEF_SIGN_KEY_PATH=\"privkey.pem\"\nexport KSEF_SIGN_CA_PATH=\"cert.pem\"\n```\n\n### Generate test cert\n\n```Bash\nKSEF_NIP=${KSEF_NIP:-2222222222}\nKSEF_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}\"\nopenssl req -x509 \\\n -nodes \\\n -subj \"${KSEF_SUBJECT}\" \\\n -days 365 \\\n -newkey rsa \\\n -keyout $KSEF_SIGN_KEY_PATH \\\n -out $KSEF_SIGN_CERT_PATH\n```\n\n### Run pytest framework\n\n```Bash\n(ksef) $ pip install -r requirements.txt\n(ksef) $ pytest -svvv\n```\n\n### Markers\n\nRun all e2e/functional/current tests\n```\n(ksef) $ pytest -svvv tests/test_ksef.py -m \"e2e and not ignore\"\n(ksef) $ pytest -svvv tests/test_ksef.py -m \"functional and not ignore\"\n(ksef) $ pytest -svvv tests/test_ksef.py -m \"current and not ignore\"\n(ksef) $ ./run_tests.sh\n(ksef) $ TESTS_MARKERS=\"init_signed and functional and not ignore\" ./run_tests.sh\n```\n\n## Example\n\nSee [tests/test_e2e.py](tests/test_e2e.py) for detailed examples of usage.\n\n```Python\nfrom ksef_utils.server import KSEFServer, KSEFService\nfrom ksef_utils.config import TestConfig, DemoConfig, ProdConfig\n\nconfig = TestConfig()\nserver = KSEFServer(config)\nservice = KSEFService(service)\n\ninvoice_data = {\n # ...\n # see tests/conftest.py for example json invoice\n}\n\nsession_token = service.init_signed()\nresponse_send_invoice = service.send_invoice(**invoice_data)\n```\n\n## Using cli utilities\n\n```\n(ksef) $ python -m ksef_utils --identifier 1111111111 --identifier_type NIP --working_directory .\n(ksef) $ pip install .\n(ksef) $ which ksef-utils\n(...)/.envs/bin/ksef-utils\n(ksef) $ ksef-utils --identifier 1111111111 --identifier_type PESEL --working_directory .\n```\n\n## OpenAPI\n\n```\n/openapi/gtw/svc/api/KSeF-common.yaml\n/openapi/gtw/svc/api/KSeF-batch.yaml\n/openapi/gtw/svc/api/KSeF-online.yaml\n```\n\n## Publish new release\n\n```Bash\n$ git tag v1.0\n$ git push origin v1.0\n```\n\n## Building documentation\n\n```Bash\n(ksef) $ sphinx-build -M html docs docs_build\n```\n\n## KSEF references\n\n* https://www.podatki.gov.pl/ksef/\n* https://ksef-test.mf.gov.pl/web/\n* https://www.youtube.com/watch?v=dnBGO6IPtzA\n\n## Contributing\n\n* https://www.conventionalcommits.org/en/v1.0.0/\n",
"bugtrack_url": null,
"license": "",
"summary": "",
"version": "1.3",
"project_urls": {
"Homepage": "https://github.com/pprzetacznik/ksef-utils"
},
"split_keywords": [
"invoices",
"ksef"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "77e0f439a10994dfaab08c51e307bcc2984dcd2e37dd6990c666080560505122",
"md5": "3caccb9703990856efa988c58b560a18",
"sha256": "1c62584af1d137816364e50361e362dd3f561bf5a5647c60c46a8216da9863ad"
},
"downloads": -1,
"filename": "ksef_utils-1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3caccb9703990856efa988c58b560a18",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 13164,
"upload_time": "2024-01-31T21:29:11",
"upload_time_iso_8601": "2024-01-31T21:29:11.392140Z",
"url": "https://files.pythonhosted.org/packages/77/e0/f439a10994dfaab08c51e307bcc2984dcd2e37dd6990c666080560505122/ksef_utils-1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8177b457f425047a2befa6f589086456558e9cf98d138613dc41efc84eba6d47",
"md5": "1a85094e75bdc79b6ba64bcde4f08e94",
"sha256": "6027b9b639826365a6ac98fdf0ec0d877a92241f435aaec9d5c891bb1c6afd05"
},
"downloads": -1,
"filename": "ksef-utils-1.3.tar.gz",
"has_sig": false,
"md5_digest": "1a85094e75bdc79b6ba64bcde4f08e94",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 29061,
"upload_time": "2024-01-31T21:29:13",
"upload_time_iso_8601": "2024-01-31T21:29:13.322457Z",
"url": "https://files.pythonhosted.org/packages/81/77/b457f425047a2befa6f589086456558e9cf98d138613dc41efc84eba6d47/ksef-utils-1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-31 21:29:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pprzetacznik",
"github_project": "ksef-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "pytest-bdd",
"specs": []
},
{
"name": "Jinja2",
"specs": []
},
{
"name": "pycryptodome",
"specs": []
},
{
"name": "lxml",
"specs": []
},
{
"name": "pytz",
"specs": []
},
{
"name": "signxml",
"specs": [
[
"==",
"3.2.1"
]
]
},
{
"name": "Sphinx",
"specs": []
}
],
"lcname": "ksef-utils"
}