theawiteb / fatoora

An unofficial package help developers to implement ZATCA (Fatoora) QR code easily which required for e-invoicing

Archived, see #23

ZATCA (Fatoora) QR-Code Implementation

An unofficial package help developers to implement ZATCA (Fatoora) QR code easily which required for e-invoicing

Table of Contents

1. Requirements
2. Installation
   • With PyPi
   • With GitHub
3. Usage
   • variables
   • Generate Base64
   • Render A QR Code Image
     • The content is the base64 of the invoice
     • The content is the invoice url
   • Generate hash (sha256)
   • Read qr code
   • Extra Methods
   • Extra Functions
4. Discussions
5. Issues
6. Security
7. Donating
8. Project use this package
9. License

Requirements

• Python >= 3.8

Installation

PyPi

$ pip3 install fatoora

GitHub

$ git clone https://github.com/TheAwiteb/fatoora/
$ cd fatoora
$ python3 setup.py install

Usage

Variables

Here the features of the variables of the Fatoora class will be explained

• Seller’s name.
• Seller’ tax number, which is the VAT registration number.
• Invoice date, which is the timestamp of the electronic invoice.
• Invoice total amount, which is the electronic invoice total with VAT.
• Tax amount, which is the VAT total.

Name	Feature	How will it be in the tag	How will it be when you call
seller_name	saved directly without processing	No changes will be made to it	No changes will be made to it
tax_number	receives the tax number as a text and a number as well, and save it as string	number as string	number as string
invoice_date	receives the date as timestamp or datetime object, or string ISO 8601 Zulu format	string of date as ISO 8601 Zulu format	datetime object
total_amount	receives the tax number as a text and a number as well	It is of type str as float	It is of type float
tax_amount	same total_amount + Accept None value to get VAT auto from total_amount	same total_amount	same total_amount

Note: The tax_amount is rounded to the nearest two decimal places, if it is greater than that ( if tax_amount == 15 its will be 15.0)

Note: If you set tax_amount to None the vat_rates == 0.15 you can change it in Fatoora object

Generate Base64

from fatoora import Fatoora

fatoora_obj = Fatoora(
    seller_name="Awiteb",
    tax_number=1234567891, # or "1234567891"
    invoice_date=1635872693.3186214, # timestamp or datetime object, or string ISO 8601 Zulu format
    total_amount=100, # or 100.0, 100.00, "100.0", "100.00"
    tax_amount=15, # or 15.0, 15.00, "15.0", "15.00"
)

print(fatoora_obj.base64)
# AQZBd2l0ZWICCjEyMzQ1Njc4OTEDFDIwMjEtMTEtMDJUMTc6MDQ6NTNaBAUxMDAuMAUEMTUuMA==

Render A QR Code Image

You can render the tags as QR code image easily

The content is the base64 of the invoice

from fatoora import Fatoora

fatoora_obj = Fatoora(
    seller_name="Awiteb",
    tax_number=1234567891,
    invoice_date=1635872693.3186214,
    total_amount=100,
    tax_amount=15,
)

fatoora_obj.qrcode("qr_code.png")

The content is the invoice url

from fatoora import Fatoora

fatoora_obj = Fatoora(
    seller_name="Awiteb",
    tax_number=1234567891,
    invoice_date=1635872693.3186214,
    total_amount=100,
    tax_amount=15,
    qrcode_url="https://example.com"
)

fatoora_obj.qrcode("qr_code_with_url.png")

Generate hash (sha256)

from fatoora import Fatoora

fatoora_obj = Fatoora(
    seller_name="Awiteb",
    tax_number=1234567891, 
    invoice_date=1635872693.3186214,
    total_amount=100, 
    tax_amount=15, 
)

print(fatoora_obj.hash)
# 20b8ddb6ed9cb98be3d8535a1f4f28e35888842c1b0aed0e90c3e7fb51080dd9

Read qr code

from fatoora import Fatoora

fatoora_obj = Fatoora(
    seller_name="Awiteb",
    tax_number=1234567891, 
    invoice_date=1635872693.3186214,
    total_amount=100, 
    tax_amount=15, 
)

fatoora_obj.qrcode("qr_code.png")

print(Fatoora.read_qrcode("qr_code.png", dct=True))
# {'seller_name': 'Awiteb', 'tax_number': '1234567891', 'invoice_date': '2021-11-02T17:04:53Z', 'total_amount': '100.0', 'tax_amount': '15.0'}

print(Fatoora.read_qrcode("qr_code.png", dct=False))
# AQZBd2l0ZWICCjEyMzQ1Njc4OTEDFDIwMjEtMTEtMDJUMTc6MDQ6NTNaBAUxMDAuMAUEMTUuMA==

Extra Methods

from fatoora import Fatoora
fatoora_obj = Fatoora(
    seller_name="Awiteb",
    tax_number=1234567891, 
    invoice_date=1635872693.3186214,
    total_amount=100, 
    tax_amount=15, 
)

print(fatoora_obj.invoice_date.year)
# 2021

print(fatoora_obj.invoice_date.isoformat())
# 2021-11-02T17:04:53

print(fatoora_obj.invoice_date.timestamp())
# 1635861893.0

print(fatoora_obj.json())
# '{"seller_name": "Awiteb", "tax_number": "1234567891", "invoice_date": "2021-11-02T17:04:53Z", "total_amount": "100.0", "tax_amount": "15.0"}'

print(fatoora_obj.dict())
# {'seller_name': 'Awiteb', 'tax_number': '1234567891', 'invoice_date': '2021-11-02T17:04:53Z', 'total_amount': '100.0', 'tax_amount': '15.0'}

# Use class to get fatoora details by base64

print(Fatoora.base2dict(fatoora_obj.base64))
# {'seller_name': 'Awiteb', 'tax_number': '1234567891', 'invoice_date': '2021-11-02T17:04:53Z', 'total_amount': '100.0', 'tax_amount': '15.0'}

Extra Functions

import fatoora

print(fatoora.is_valid_iso8601_zulu_format("invalid date"))
# False

print(fatoora.is_valid_iso8601_zulu_format("2021-11-02T17:04:53Z"))
# True

Discussions

Question, feature request, discuss about fatoora here

Issues

You can report a bug from here

Security

If you discover any security related issues.

Donating

Currency	Address
Binance BNB BEP20	0xD89c146B03B72191be91064D313610981dCAF6d4
USD Coin USDC BEP20	0xD89c146B03B72191be91064D313610981dCAF6d4
Bitcoin BTC	bc1q0ltmqmsc4qs740ssyf9k9jq99nwxtqu8aupmdj
Bitcoin Cash BCH	qrpm6zyte3d4z2u9r24l04m3havc2wd9vgqlz8sjgr

License

The MIT License (MIT). Please see License File for more information.

fatoora's Issues

invoice date timestamp not work with VAT app

you have issue with invoice date timestamp
invoice date must be datetime as string not timestamp float..

datetime must be convert to string using this patch code:

invoice_date.isoformat()[:-6] + "Z",

---

Thank you for this package
Best regards,

[Bug]: `read_qrcode` panic when read a qr code contain a url

Checks

• I added a descriptive title to this issue
• I have searched (google, github) for similar issues and couldn't find anything
• I have read and followed the docs and still think this is a bug

Bug

When trying to read a qr code contain a url and set the value of dct to True, the function will panic

Code

from fatoora import Fatoora


obj = Fatoora(
    seller_name="Awiteb",
    tax_number=1234567891,
    invoice_date=1635872693.3186214,
    total_amount=100,
    tax_amount=15,
    qrcode_url="https://example.com",
)

obj.qrcode("tests.png")
obj.read_qrcode("tests.png", dct=True)

Error message

Traceback (most recent call last):
  File "~/Desktop/projects/python-projects/fatoora/t.py", line 14, in <module>
    obj.read_qrcode("tests.png", dct=True)
  File "~/Desktop/projects/python-projects/fatoora/fatoora/fatoora.py", line 127, in read_qrcode
    return cls.base2dict(data)
  File "~/Desktop/projects/python-projects/fatoora/fatoora/fatoora.py", line 98, in base2dict
    decoded = base64.b64decode(base)
  File "/usr/lib/python3.10/base64.py", line 87, in b64decode
    return binascii.a2b_base64(s)
binascii.Error: Invalid base64-encoded string: number of data characters (17) cannot be 1 more than a multiple of 4

Make zbar optional, or replace it

Bug

zbar is an old library that is being removed from different Linux repositories.
I suggest that instead of make it a mandatory, we make it optional (via a try/except) and the read_qrcode throws an exception if zbar is not installed (as I see, it's used only for decoding the QR image).

Or (better), we replace it with something else, if exists.

Thanks for working on this. Helped a lot implementing ZATCA's e-invoicing :)