# Billing Yard
Billing Yard is an open source CLI tool written in Python 3 for generating invoices as PDF files
from [JSON](https://www.json.org) for business entities in the Czech republic. It supports invoices for both VAT payers
and non VAT payers and generates a QR code with payment information for Czech banks.
If you like this software, please [buy me a coffee](https://www.buymeacoffee.com/martinvondrak).
## Installation
First, please note that the software has [WeasyPrint](https://weasyprint.org) as a dependency and WeasyPrint needs some
external third party libraries for correct functioning. The way to install these libraries will differ based on your
operating system. So first you need to install these dependencies according to the manual below, then you can install
Billing Yard itself.
The installation manual below expects you to know and understand how to work with [pip](https://pip.pypa.io)
and [Virtual Environment](https://docs.python.org/3/tutorial/venv.html).
### Linux
Below, you can find how to install external third party libraries on different Linux distributions.
#### Debian
Debian 11 Bullseye or newer
```shell
apt install python3-pip libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0
```
#### Ubuntu
Ubuntu 20.04 Focal Fossa or newer
```shell
apt install python3-pip libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0 libharfbuzz-subset0
```
#### Fedora
Fedora 39 or newer
```shell
dnf install python-pip pango
```
#### Archlinux
```shell
pacman -S python-pip pango
```
#### Alpine
Alpine Linux 3.17 or newer
```shell
apk add py3-pip so:libgobject-2.0.so.0 so:libpango-1.0.so.0 so:libharfbuzz.so.0 so:libharfbuzz-subset.so.0 so:libfontconfig.so.1 so:libpangoft2-1.0.so.0
```
### macOS
Installation on macOS is recommended via [Homebrew](https://brew.sh).
```shell
brew install python3 pango libffi
```
### Windows and further support
For installation on Windows or further support, please see the
official [WeasyPrint installation guide](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#windows). But
please keep in mind that WeasyPrint must be installed as a dependency of Billing Yard and not directly using your OS
package manager.
### Installing Billing Yard
First you need to decide whether you want to use Virtual Environment or install Billing Yard globally. But note that
installing in Virtual Environment is always preferred way. Then just make sure you are using Python 3.9 or newer and
run following command, and you are done.
```shell
pip install billingyard
```
## Basic usage
First step is to create configuration and data source files for generating an invoice. All configuration and data
sources for an invoice are stored in JSON files. There are three schemas of JSON files, one for business entity (sender,
receiver), one for an invoice without VAT and one for an invoice with VAT. Then you can generate the invoice itself.
### Business entity
We create two business entities, sender (entity which issues the invoice) and receiver (entity which pays the invoice).
```json
{
"company": "Company s.r.o.",
"street": "Ulice 38",
"city": "Praha",
"zip_code": "100 00",
"country": "Česká republika",
"company_id": "00011000",
"vat_id": "CZ00011000"
}
```
* **company** - the business name of the business entity
* **street** - the street in the address of the business entity
* **city** - the city in the address of the business entity
* **zip_code** - the zip code in the address of the business entity
* **country** - the country in the address of the business entity
* **company** - the identifier given by Czech authority of the business entity
* **vat_id** - the identifier for VAT purpose of the business entity
* optional if business entity is not a VAT payer
### Invoice for a non VAT payer
Below you can find the self explaining example of a non VAT payer invoice with further description.
```json
{
"invoice_number": "2021001",
"issue_date": "01. 01. 2021",
"due_date": "31. 01. 2021",
"currency": "Kč",
"bank": "Bank a.s.",
"bank_account": "1234567890/1234",
"iban": "CZ4100000000000123456789",
"payment_method": "bank transfer",
"register_info": "Fyzická osoba zapsaná v živnostenském rejstříku.",
"invoice_lines": [
{
"description": "software development",
"unit": "hr",
"quantity": 20,
"unit_price": 1500
}
]
}
```
* **invoice_number** - a unique identifier of the invoice
* completely up to you, but keep in mind local policies from government
* **issue_date** - the date of issue of the invoice
* optional, if not set current date is used
* **due_date** - the last day, when the invoice must be paid
* **currency** - the currency in which is the invoice issued
* **bank** - the bank of the sender business entity
* **bank_account** - the bank account number of the sender business entity
* **iban** - the IBAN of the sender business entity
* optional, if not set, the QR code with payment information are not generated in the invoice
* **payment_method** - the agreed instrument to pay the invoice
* e.g. bank transfer, cash, credit card
* this text is directly rendered in the invoice
* **register_info** - the info about record in government registers of the sender business entity
* the typical examples in Czech are "Fyzická osoba zapsaná v živnostenském rejstříku." or "Společnost je zapsána v
obchodním rejstříku vedeném u Městského soudu v Praze, oddílu C, vložce 2396."
* **invoice_lines** - the list of items that are invoiced
Each invoice line consists of following properties.
* **description** - the name or more exhaustive description of the invoiced item
* **unit** - the unit which we can use to count the invoiced item
* e.g. hour, piece, meter, square meter etc
* **quantity** - the amount of invoiced items in previously specified unit
* **unit_price** - the price of the invoiced item for one unit
All dates have `DD. MM. YYYY` format.
### Invoice for a VAT payer
Below you can find the self explaining example of a VAT payer invoice with further description.
```json
{
"invoice_number": "2021001",
"issue_date": "01. 01. 2021",
"supply_date": "01. 01. 2021",
"due_date": "31. 01. 2021",
"currency": "Kč",
"bank": "Bank a.s.",
"bank_account": "1234567890/1234",
"iban": "CZ4100000000000123456789",
"payment_method": "bank transfer",
"register_info": "Fyzická osoba zapsaná v živnostenském rejstříku.",
"invoice_lines": [
{
"description": "software development",
"unit": "hr",
"quantity": 20,
"unit_price": 1500,
"vat_rate": 0.21
}
]
}
```
* **invoice_number** - a unique identifier of the invoice
* completely up to you, but keep in mind local policies from government
* **issue_date** - the date of issue of the invoice
* optional, if not set current date is used
* **supply_date** - the date of taxable supply
* optional, if not set current date is used
* **due_date** - the last day, when the invoice must be paid
* **currency** - the currency in which is the invoice issued
* **bank** - the bank of the sender business entity
* **bank_account** - the bank account number of the sender business entity
* **iban** - the IBAN of the sender business entity
* optional, if not set, the QR code with payment information are not generated in the invoice
* **payment_method** - the agreed instrument to pay the invoice
* e.g. bank transfer, cash, credit card
* this text is directly rendered in the invoice
* **register_info** - the info about record in government registers of the sender business entity
* the typical examples in Czech are "Fyzická osoba zapsaná v živnostenském rejstříku." or "Společnost je zapsána v
obchodním rejstříku vedeném u Městského soudu v Praze, oddílu C, vložce 2396."
* **invoice_lines** - the list of items that are invoiced
Each invoice line consists of following properties.
* **description** - the name or more exhaustive description of the invoiced item
* **unit** - the unit which we can use to count the invoiced item
* e.g. hour, piece, meter, square meter etc
* **quantity** - the amount of invoiced items in previously specified unit
* **unit_price** - the price of the invoiced item for one unit without VAT
* **vat_rate** - the rate of VAT for this invoiced item
All dates have `DD. MM. YYYY` format.
### Generating an invoice
If you installed Billing Yard using Virtual Environment, just activate this environment and run one of the following
commands, depending on whether you are a VAT payer or not. If you installed Billing Yard globally, just run one of the
commands.
```shell
billingyard -s sender.json issue-invoice -i invoice.json -r receiver.json
```
The option `-s` expects path to JSON data file with information about a sender business entity. It can be omitted, if
its name is `sender.json` and it is located in the same directory from which is the command executed.
The option `-i` expects path to JSON data file with the invoice data.
The option `-r` expects path to JSON data file with information about a sender business entity.
```shell
billingyard -s sender.json issue-invoice -i invoice_vat.json -r receiver.json --vat
```
The option `--vat` is used to generate an invoice for a VAT payer sender business entity. Please do not forget, that in
this case, you have to also provide correct invoice JSON data file with all needed attributes.
## License
This software is released under MIT License and use other third party software.
* [Click](https://github.com/pallets/click/blob/main/LICENSE.txt)
* [Jinja2](https://github.com/pallets/jinja/blob/main/LICENSE.txt)
* [WeasyPrint](https://github.com/Kozea/WeasyPrint/blob/master/LICENSE)
* [qrcode](https://github.com/lincolnloop/python-qrcode/blob/main/LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/MartinVondrak/billing-yard",
"name": "billingyard",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "invoice, cli, generator",
"author": "Martin Vondr\u00e1k",
"author_email": "martin@martinvondrak.cz",
"download_url": "https://files.pythonhosted.org/packages/ea/74/46c9816ad55fa64a921760cf7c231267eea775e35b7982b3f3b93f14444d/billingyard-1.2.0.tar.gz",
"platform": null,
"description": "# Billing Yard\n\nBilling Yard is an open source CLI tool written in Python 3 for generating invoices as PDF files\nfrom [JSON](https://www.json.org) for business entities in the Czech republic. It supports invoices for both VAT payers\nand non VAT payers and generates a QR code with payment information for Czech banks.\n\nIf you like this software, please [buy me a coffee](https://www.buymeacoffee.com/martinvondrak).\n\n## Installation\n\nFirst, please note that the software has [WeasyPrint](https://weasyprint.org) as a dependency and WeasyPrint needs some\nexternal third party libraries for correct functioning. The way to install these libraries will differ based on your\noperating system. So first you need to install these dependencies according to the manual below, then you can install\nBilling Yard itself.\n\nThe installation manual below expects you to know and understand how to work with [pip](https://pip.pypa.io)\nand [Virtual Environment](https://docs.python.org/3/tutorial/venv.html).\n\n### Linux\n\nBelow, you can find how to install external third party libraries on different Linux distributions.\n\n#### Debian\n\nDebian 11 Bullseye or newer\n\n```shell\napt install python3-pip libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0\n```\n\n#### Ubuntu\n\nUbuntu 20.04 Focal Fossa or newer\n\n```shell\napt install python3-pip libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0 libharfbuzz-subset0\n```\n\n#### Fedora\n\nFedora 39 or newer\n\n```shell\ndnf install python-pip pango\n```\n\n#### Archlinux\n\n```shell\npacman -S python-pip pango\n```\n\n#### Alpine\n\nAlpine Linux 3.17 or newer\n\n```shell\napk add py3-pip so:libgobject-2.0.so.0 so:libpango-1.0.so.0 so:libharfbuzz.so.0 so:libharfbuzz-subset.so.0 so:libfontconfig.so.1 so:libpangoft2-1.0.so.0\n```\n\n### macOS\n\nInstallation on macOS is recommended via [Homebrew](https://brew.sh).\n\n```shell\nbrew install python3 pango libffi\n```\n\n### Windows and further support\n\nFor installation on Windows or further support, please see the\nofficial [WeasyPrint installation guide](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#windows). But\nplease keep in mind that WeasyPrint must be installed as a dependency of Billing Yard and not directly using your OS\npackage manager.\n\n### Installing Billing Yard\n\nFirst you need to decide whether you want to use Virtual Environment or install Billing Yard globally. But note that\ninstalling in Virtual Environment is always preferred way. Then just make sure you are using Python 3.9 or newer and\nrun following command, and you are done.\n\n```shell\npip install billingyard\n```\n\n## Basic usage\n\nFirst step is to create configuration and data source files for generating an invoice. All configuration and data\nsources for an invoice are stored in JSON files. There are three schemas of JSON files, one for business entity (sender,\nreceiver), one for an invoice without VAT and one for an invoice with VAT. Then you can generate the invoice itself.\n\n### Business entity\n\nWe create two business entities, sender (entity which issues the invoice) and receiver (entity which pays the invoice).\n\n```json\n{\n \"company\": \"Company s.r.o.\",\n \"street\": \"Ulice 38\",\n \"city\": \"Praha\",\n \"zip_code\": \"100 00\",\n \"country\": \"\u010cesk\u00e1 republika\",\n \"company_id\": \"00011000\",\n \"vat_id\": \"CZ00011000\"\n}\n```\n\n* **company** - the business name of the business entity\n* **street** - the street in the address of the business entity\n* **city** - the city in the address of the business entity\n* **zip_code** - the zip code in the address of the business entity\n* **country** - the country in the address of the business entity\n* **company** - the identifier given by Czech authority of the business entity\n* **vat_id** - the identifier for VAT purpose of the business entity\n * optional if business entity is not a VAT payer\n\n### Invoice for a non VAT payer\n\nBelow you can find the self explaining example of a non VAT payer invoice with further description.\n\n```json\n{\n \"invoice_number\": \"2021001\",\n \"issue_date\": \"01. 01. 2021\",\n \"due_date\": \"31. 01. 2021\",\n \"currency\": \"K\u010d\",\n \"bank\": \"Bank a.s.\",\n \"bank_account\": \"1234567890/1234\",\n \"iban\": \"CZ4100000000000123456789\",\n \"payment_method\": \"bank transfer\",\n \"register_info\": \"Fyzick\u00e1 osoba zapsan\u00e1 v \u017eivnostensk\u00e9m rejst\u0159\u00edku.\",\n \"invoice_lines\": [\n {\n \"description\": \"software development\",\n \"unit\": \"hr\",\n \"quantity\": 20,\n \"unit_price\": 1500\n }\n ]\n}\n```\n\n* **invoice_number** - a unique identifier of the invoice\n * completely up to you, but keep in mind local policies from government\n* **issue_date** - the date of issue of the invoice\n * optional, if not set current date is used\n* **due_date** - the last day, when the invoice must be paid\n* **currency** - the currency in which is the invoice issued\n* **bank** - the bank of the sender business entity\n* **bank_account** - the bank account number of the sender business entity\n* **iban** - the IBAN of the sender business entity\n * optional, if not set, the QR code with payment information are not generated in the invoice\n* **payment_method** - the agreed instrument to pay the invoice\n * e.g. bank transfer, cash, credit card\n * this text is directly rendered in the invoice\n* **register_info** - the info about record in government registers of the sender business entity\n * the typical examples in Czech are \"Fyzick\u00e1 osoba zapsan\u00e1 v \u017eivnostensk\u00e9m rejst\u0159\u00edku.\" or \"Spole\u010dnost je zaps\u00e1na v\n obchodn\u00edm rejst\u0159\u00edku veden\u00e9m u M\u011bstsk\u00e9ho soudu v Praze, odd\u00edlu C, vlo\u017ece 2396.\"\n* **invoice_lines** - the list of items that are invoiced\n\nEach invoice line consists of following properties.\n\n* **description** - the name or more exhaustive description of the invoiced item\n* **unit** - the unit which we can use to count the invoiced item\n * e.g. hour, piece, meter, square meter etc\n* **quantity** - the amount of invoiced items in previously specified unit\n* **unit_price** - the price of the invoiced item for one unit\n\nAll dates have `DD. MM. YYYY` format.\n\n### Invoice for a VAT payer\n\nBelow you can find the self explaining example of a VAT payer invoice with further description.\n\n```json\n{\n \"invoice_number\": \"2021001\",\n \"issue_date\": \"01. 01. 2021\",\n \"supply_date\": \"01. 01. 2021\",\n \"due_date\": \"31. 01. 2021\",\n \"currency\": \"K\u010d\",\n \"bank\": \"Bank a.s.\",\n \"bank_account\": \"1234567890/1234\",\n \"iban\": \"CZ4100000000000123456789\",\n \"payment_method\": \"bank transfer\",\n \"register_info\": \"Fyzick\u00e1 osoba zapsan\u00e1 v \u017eivnostensk\u00e9m rejst\u0159\u00edku.\",\n \"invoice_lines\": [\n {\n \"description\": \"software development\",\n \"unit\": \"hr\",\n \"quantity\": 20,\n \"unit_price\": 1500,\n \"vat_rate\": 0.21\n }\n ]\n}\n```\n\n* **invoice_number** - a unique identifier of the invoice\n * completely up to you, but keep in mind local policies from government\n* **issue_date** - the date of issue of the invoice\n * optional, if not set current date is used\n* **supply_date** - the date of taxable supply\n * optional, if not set current date is used\n* **due_date** - the last day, when the invoice must be paid\n* **currency** - the currency in which is the invoice issued\n* **bank** - the bank of the sender business entity\n* **bank_account** - the bank account number of the sender business entity\n* **iban** - the IBAN of the sender business entity\n * optional, if not set, the QR code with payment information are not generated in the invoice\n* **payment_method** - the agreed instrument to pay the invoice\n * e.g. bank transfer, cash, credit card\n * this text is directly rendered in the invoice\n* **register_info** - the info about record in government registers of the sender business entity\n * the typical examples in Czech are \"Fyzick\u00e1 osoba zapsan\u00e1 v \u017eivnostensk\u00e9m rejst\u0159\u00edku.\" or \"Spole\u010dnost je zaps\u00e1na v\n obchodn\u00edm rejst\u0159\u00edku veden\u00e9m u M\u011bstsk\u00e9ho soudu v Praze, odd\u00edlu C, vlo\u017ece 2396.\"\n* **invoice_lines** - the list of items that are invoiced\n\nEach invoice line consists of following properties.\n\n* **description** - the name or more exhaustive description of the invoiced item\n* **unit** - the unit which we can use to count the invoiced item\n * e.g. hour, piece, meter, square meter etc\n* **quantity** - the amount of invoiced items in previously specified unit\n* **unit_price** - the price of the invoiced item for one unit without VAT\n* **vat_rate** - the rate of VAT for this invoiced item\n\nAll dates have `DD. MM. YYYY` format.\n\n### Generating an invoice\n\nIf you installed Billing Yard using Virtual Environment, just activate this environment and run one of the following\ncommands, depending on whether you are a VAT payer or not. If you installed Billing Yard globally, just run one of the\ncommands.\n\n```shell\nbillingyard -s sender.json issue-invoice -i invoice.json -r receiver.json\n```\n\nThe option `-s` expects path to JSON data file with information about a sender business entity. It can be omitted, if\nits name is `sender.json` and it is located in the same directory from which is the command executed.\n\nThe option `-i` expects path to JSON data file with the invoice data.\n\nThe option `-r` expects path to JSON data file with information about a sender business entity.\n\n```shell\nbillingyard -s sender.json issue-invoice -i invoice_vat.json -r receiver.json --vat\n```\n\nThe option `--vat` is used to generate an invoice for a VAT payer sender business entity. Please do not forget, that in\nthis case, you have to also provide correct invoice JSON data file with all needed attributes.\n\n## License\n\nThis software is released under MIT License and use other third party software.\n\n* [Click](https://github.com/pallets/click/blob/main/LICENSE.txt)\n* [Jinja2](https://github.com/pallets/jinja/blob/main/LICENSE.txt)\n* [WeasyPrint](https://github.com/Kozea/WeasyPrint/blob/master/LICENSE)\n* [qrcode](https://github.com/lincolnloop/python-qrcode/blob/main/LICENSE)\n",
"bugtrack_url": null,
"license": null,
"summary": "CLI invoice generator for business entities in the Czech republic",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/MartinVondrak/billing-yard"
},
"split_keywords": [
"invoice",
" cli",
" generator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e8b971934cee95014fe2b8610c7db1a9e22f6a94ff84a909302836537842758b",
"md5": "18b9d64f72b516d2b5f255cef33de109",
"sha256": "8bf4a0a14d38e076a1995b7e64009b255fb27598642b7d06d1f4e35d2367ebf4"
},
"downloads": -1,
"filename": "billingyard-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "18b9d64f72b516d2b5f255cef33de109",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13725,
"upload_time": "2024-12-11T10:05:59",
"upload_time_iso_8601": "2024-12-11T10:05:59.744419Z",
"url": "https://files.pythonhosted.org/packages/e8/b9/71934cee95014fe2b8610c7db1a9e22f6a94ff84a909302836537842758b/billingyard-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ea7446c9816ad55fa64a921760cf7c231267eea775e35b7982b3f3b93f14444d",
"md5": "90994bcc9cbf0c64bb1df69b29b275d1",
"sha256": "60133b44f816d812ad7077c3262b4f3ba137df97d2d99e05d6976897a912faf9"
},
"downloads": -1,
"filename": "billingyard-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "90994bcc9cbf0c64bb1df69b29b275d1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13648,
"upload_time": "2024-12-11T10:06:01",
"upload_time_iso_8601": "2024-12-11T10:06:01.161101Z",
"url": "https://files.pythonhosted.org/packages/ea/74/46c9816ad55fa64a921760cf7c231267eea775e35b7982b3f3b93f14444d/billingyard-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-11 10:06:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MartinVondrak",
"github_project": "billing-yard",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "billingyard"
}
JSON
