Metadata-Version: 2.4
Name: django-ticketbai
Version: 2.3
Summary: django-ticketbai allows to create, manage, store and send TicketBai invoices to the Basque tax authorities.
Home-page: https://github.com/codesyntax/django-ticketbai
Author: Urtzi Odriozola
Author-email: uodriozola@codesyntax.com
License: Copyright 2023 CodeSyntax
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytbai>=1.7.0
Requires-Dist: qrcode
Requires-Dist: weasyprint==63.1
Requires-Dist: crc8==0.2.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-ticketbai)
![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/codesyntax/django-ticketbai/python-package.yml)
![PyPI - Version](https://img.shields.io/pypi/v/django-ticketbai)

# django-ticketbai

django-ticketbai allows to create, manage, store and send TicketBai invoices to the Basque tax authorities.

## Requirements

- Python 3.11 or newer
- Django 4.2 or 5.2

## Installation

```bash
pip install django-ticketbai
```

Add the app to `INSTALLED_APPS` and run its migrations:

```python
INSTALLED_APPS = [
    # ...
    "django_ticketbai",
]
```

```bash
python manage.py migrate django_ticketbai
```

## Configuration

Two things have to be configured:

| Data | Where |
| --- | --- |
| Issuer and software data | the `TICKETBAI_CONF` setting |
| Invoice series and signing certificate | the `Config` model (editable in the admin) |

### The `TICKETBAI_CONF` setting

`TICKETBAI_CONF` is a dictionary with two mandatory sections, `subject` (the
issuer of the invoices) and `software` (the TicketBai software declaration).
It is passed as-is to [`pytbai`](https://github.com/codesyntax/pytbai), so its
structure is the one `pytbai.TBai` expects:

```json
{
  "subject": {
    "entity_id": "B12345678",
    "name": "ACME S.L.",
    "address": "Main street 1",
    "territory": "Gipuzkoa"
  },
  "software": {
    "license": "TBAIGIPRE00000000001",
    "dev_entity": "B00000000",
    "soft_name": "django-ticketbai",
    "soft_version": "1.0"
  }
}
```

In your Django settings:

```python
TICKETBAI_CONF = {
    "subject": {
        "entity_id": "B12345678",
        "name": "ACME S.L.",
        "address": "Main street 1",
        "territory": "Gipuzkoa",
    },
    "software": {
        "license": "TBAIGIPRE00000000001",
        "dev_entity": "B00000000",
        "soft_name": "django-ticketbai",
        "soft_version": "1.0",
    },
}
```

#### `subject`

| Key | Required | Default | Description |
| --- | --- | --- | --- |
| `entity_id` | yes | – | Tax id (NIF) of the issuer |
| `name` | yes | – | Name of the issuer |
| `address` | no | `None` | Address shown in the invoice PDF |
| `territory` | no | `"Gipuzkoa"` | `Araba`, `Bizkaia` or `Gipuzkoa` |
| `multi_recipient` | no | `"N"` | `S` (yes) or `N` (no) |
| `external_invoice` | no | `"N"` | `N`, `T` or `D`, see `pytbai.definitions.L4` |

#### `software`

| Key | Required | Default | Description |
| --- | --- | --- | --- |
| `license` | yes | – | TicketBai licence of the software |
| `dev_entity` | yes | – | Tax id (NIF) of the software developer |
| `soft_name` | yes | – | Name of the software |
| `soft_version` | yes | – | Version of the software |

#### Notes

- Do **not** add `env` to `TICKETBAI_CONF`: `django-ticketbai` sets it
  automatically.
- Test or production endpoint is chosen with the `DEBUG` setting:
  `DEBUG = True` sends the invoices to the testing environment and
  `DEBUG = False` to the production one. Make sure `DEBUG` is `False` in
  production, otherwise the invoices are not sent to the Basque tax
  authorities but to the test service.
- The models are registered in the Django admin only when the
  `TICKETBAI_CONF` setting is defined.
- The bundled test view (`django_ticketbai.views.test_send_and_store_invoice`)
  answers `KO` when the setting is missing.

### The `Config` model

The `Config` model holds the data that can change between installations, and it
is meant to be edited in the Django admin:

| Field | Description |
| --- | --- |
| `prefix`, `suffix` | Invoice series |
| `pks12` | PKCS#12 (`.p12`) certificate used to sign the invoices |
| `password` | Password of the certificate |
| `logo` | Optional logo shown in the invoice PDF |
| `is_active` | Only the active configuration is used |

At least one active `Config` object is required before creating an invoice.

## Usage

```python
from django.conf import settings

from django_ticketbai.utils.invoice import create_one_line_simplified_invoice

invoice = create_one_line_simplified_invoice(
    settings.TICKETBAI_CONF,
    "Simplified invoice",  # invoice description
    "customer@example.com",  # recipient email
    "Product",  # line description
    "1",  # quantity
    "200",  # unit price
)
```

The invoice is signed with the certificate of the active `Config`, stored, and
sent to the corresponding endpoint. The signature of the previous invoice is
chained automatically. The PDF is stored in the `pdf` field of the invoice.
