faturapt 0.1.0__py3-none-any.whl

faturapt/__init__.py

@@ -0,0 +1,22 @@
+"""Leitura e validação do código QR das faturas portuguesas e de NIFs."""
+
+from .image import read_image
+from .nif import InvalidNIF, NifType, is_valid_nif, nif_type, normalize_nif
+from .qr import DOCUMENT_TYPES, InvoiceQR, QRCodeError, TaxBreakdown, check, parse
+
+__all__ = [
+    "DOCUMENT_TYPES",
+    "InvalidNIF",
+    "InvoiceQR",
+    "NifType",
+    "QRCodeError",
+    "TaxBreakdown",
+    "check",
+    "is_valid_nif",
+    "nif_type",
+    "normalize_nif",
+    "parse",
+    "read_image",
+]
+
+__version__ = "0.1.0"

faturapt/__main__.py

@@ -0,0 +1,53 @@
+"""``faturapt "A:...*B:..."`` ou ``faturapt -i talao.jpg``: mostra a fatura em JSON e os
+problemas encontrados."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from datetime import date
+from decimal import Decimal
+from typing import Any
+
+from .image import read_image
+from .qr import QRCodeError, check, parse
+
+
+def _json(value: Any) -> Any:
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, date):
+        return value.isoformat()
+    raise TypeError(type(value).__name__)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="faturapt", description=__doc__)
+    source = parser.add_mutually_exclusive_group()
+    source.add_argument("qr", nargs="?", help="texto do código QR (por omissão, lido do stdin)")
+    source.add_argument(
+        "-i", "--imagem", help="fotografia ou digitalização da fatura (precisa de faturapt[image])"
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        if args.imagem is not None:
+            invoice = read_image(args.imagem)
+        else:
+            invoice = parse(args.qr if args.qr is not None else sys.stdin.read())
+    except (QRCodeError, ImportError, OSError) as exc:
+        print(f"erro: {exc}", file=sys.stderr)
+        return 2
+
+    data = asdict(invoice)
+    data.pop("fields")
+    data["document_type_name"] = invoice.document_type_name
+    data["problems"] = check(invoice)
+    print(json.dumps(data, default=_json, ensure_ascii=False, indent=2))
+    return 1 if data["problems"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

faturapt/image.py

@@ -0,0 +1,61 @@
+"""Leitura do código QR a partir de uma imagem (fotografia ou digitalização da fatura).
+
+Precisa das dependências opcionais: ``pip install 'faturapt[image]'``.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+from typing import TYPE_CHECKING
+
+from .qr import InvoiceQR, QRCodeError, parse
+
+if TYPE_CHECKING:
+    from PIL.Image import Image
+
+__all__ = ["read_image"]
+
+_MISSING = "Para ler imagens, instalar com: pip install 'faturapt[image]'"
+
+
+def read_image(image: str | os.PathLike[str] | bytes | Image) -> InvoiceQR:
+    """Encontra o código QR da fatura numa imagem e lê-o com :func:`parse`.
+
+    Aceita o caminho de um ficheiro, o conteúdo em ``bytes`` ou uma imagem do Pillow.
+    Respeita a orientação EXIF das fotografias do telemóvel. Se houver vários códigos
+    (por exemplo, o QR de um site ao lado), devolve o primeiro que seja de uma fatura.
+
+    Lança :class:`QRCodeError` se não houver nenhum QR de fatura na imagem, e
+    ``ImportError`` se faltarem as dependências opcionais.
+    """
+    try:
+        import zxingcpp
+        from PIL import Image as PILImage
+        from PIL import ImageOps
+    except ImportError as exc:
+        raise ImportError(_MISSING) from exc
+
+    picture: Image
+    if isinstance(image, bytes):
+        picture = PILImage.open(io.BytesIO(image))
+    elif isinstance(image, (str, os.PathLike)):
+        picture = PILImage.open(image)
+    else:
+        picture = image
+    picture = ImageOps.exif_transpose(picture).convert("L")
+
+    codes = zxingcpp.read_barcodes(
+        picture, formats=zxingcpp.BarcodeFormats(zxingcpp.BarcodeFormat.QRCode)
+    )
+    if not codes:
+        raise QRCodeError("Não encontrei nenhum código QR na imagem")
+    errors = []
+    for code in codes:
+        try:
+            return parse(code.text)
+        except QRCodeError as exc:
+            errors.append(str(exc))
+    raise QRCodeError(
+        f"Há {len(codes)} código(s) QR na imagem, mas nenhum é de uma fatura ({errors[0]})"
+    )

faturapt/nif.py

@@ -0,0 +1,91 @@
+"""Validação do NIF (Número de Identificação Fiscal) português."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+__all__ = ["InvalidNIF", "NifType", "is_valid_nif", "nif_type", "normalize_nif"]
+
+
+class InvalidNIF(ValueError):
+    """O valor não é um NIF português válido."""
+
+
+class NifType(str, Enum):
+    """Tipo de contribuinte, pelo prefixo do NIF."""
+
+    INDIVIDUAL = "pessoa singular"
+    NON_RESIDENT_INDIVIDUAL = "pessoa singular não residente"
+    COMPANY = "pessoa coletiva"
+    PUBLIC_ADMINISTRATION = "administração pública"
+    UNDIVIDED_INHERITANCE = "herança indivisa"
+    NON_RESIDENT_COMPANY = "pessoa coletiva não residente"
+    INVESTMENT_FUND = "fundo de investimento"
+    OFFICIAL_ASSIGNMENT = "atribuição oficiosa"
+    EXCEPTIONAL_REGIME = "regime excecional"
+    SOLE_TRADER = "empresário em nome individual"
+    CONDOMINIUM_OR_IRREGULAR = "condomínio ou sociedade irregular"
+    NON_RESIDENT_NO_ESTABLISHMENT = "não residente sem estabelecimento estável"
+    CIVIL_PARTNERSHIP = "sociedade civil sem personalidade jurídica"
+
+
+# Prefixos de dois dígitos primeiro: "45" tem de ganhar a "4" (que não existe sozinho).
+_PREFIXES: tuple[tuple[str, NifType], ...] = (
+    ("45", NifType.NON_RESIDENT_INDIVIDUAL),
+    ("70", NifType.UNDIVIDED_INHERITANCE),
+    ("71", NifType.NON_RESIDENT_COMPANY),
+    ("72", NifType.INVESTMENT_FUND),
+    ("74", NifType.UNDIVIDED_INHERITANCE),
+    ("75", NifType.UNDIVIDED_INHERITANCE),
+    ("77", NifType.OFFICIAL_ASSIGNMENT),
+    ("79", NifType.EXCEPTIONAL_REGIME),
+    ("90", NifType.CONDOMINIUM_OR_IRREGULAR),
+    ("91", NifType.CONDOMINIUM_OR_IRREGULAR),
+    ("98", NifType.NON_RESIDENT_NO_ESTABLISHMENT),
+    ("99", NifType.CIVIL_PARTNERSHIP),
+    ("1", NifType.INDIVIDUAL),
+    ("2", NifType.INDIVIDUAL),
+    ("3", NifType.INDIVIDUAL),
+    ("5", NifType.COMPANY),
+    ("6", NifType.PUBLIC_ADMINISTRATION),
+    ("8", NifType.SOLE_TRADER),
+)
+
+
+def normalize_nif(value: str | int) -> str:
+    """Tira espaços, pontos, hífenes e o prefixo ``PT``.
+
+    Não valida: ``normalize_nif(" PT 123 456 789 ")`` dá ``"123456789"``.
+    """
+    text = str(value).strip().upper()
+    if text.startswith("PT"):
+        text = text[2:]
+    return "".join(ch for ch in text if ch not in " .-")
+
+
+def _check_digit(first_eight: str) -> int:
+    total = sum(int(d) * w for d, w in zip(first_eight, range(9, 1, -1), strict=True))
+    remainder = total % 11
+    return 0 if remainder < 2 else 11 - remainder
+
+
+def nif_type(value: str | int) -> NifType:
+    """Devolve o tipo de contribuinte, ou lança :class:`InvalidNIF`."""
+    nif = normalize_nif(value)
+    if len(nif) != 9 or not nif.isdigit():
+        raise InvalidNIF(f"O NIF tem de ter 9 dígitos: {value!r}")
+    kind = next((t for prefix, t in _PREFIXES if nif.startswith(prefix)), None)
+    if kind is None:
+        raise InvalidNIF(f"O NIF começa por um prefixo que não existe: {value!r}")
+    if int(nif[8]) != _check_digit(nif[:8]):
+        raise InvalidNIF(f"O dígito de controlo do NIF não confere: {value!r}")
+    return kind
+
+
+def is_valid_nif(value: str | int) -> bool:
+    """``True`` se o valor (depois de :func:`normalize_nif`) for um NIF válido."""
+    try:
+        nif_type(value)
+    except InvalidNIF:
+        return False
+    return True

faturapt/qr.py

@@ -0,0 +1,341 @@
+"""Leitura do código QR das faturas portuguesas.
+
+O formato vem da Portaria n.º 195/2020 e das especificações técnicas da AT
+("Código de Barras Bidimensional - Código QR", versão 1.0, agosto de 2020):
+campos ``CHAVE:valor`` separados por ``*``, por exemplo
+``A:123456789*B:999999990*C:PT*D:FT*...``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from decimal import Decimal, InvalidOperation
+
+from .nif import is_valid_nif
+
+__all__ = [
+    "DOCUMENT_TYPES",
+    "InvoiceQR",
+    "QRCodeError",
+    "TaxBreakdown",
+    "check",
+    "parse",
+]
+
+
+class QRCodeError(ValueError):
+    """O texto não é um código QR de fatura bem formado."""
+
+
+DOCUMENT_TYPES: dict[str, str] = {
+    "FT": "Fatura",
+    "FS": "Fatura simplificada",
+    "FR": "Fatura-recibo",
+    "ND": "Nota de débito",
+    "NC": "Nota de crédito",
+    "GR": "Guia de remessa",
+    "GT": "Guia de transporte",
+    "GA": "Guia de movimentação de ativos próprios",
+    "GC": "Guia de consignação",
+    "GD": "Guia ou nota de devolução",
+    "CM": "Consulta de mesa",
+    "CC": "Crédito de consignação",
+    "FC": "Fatura de consignação",
+    "FO": "Folha de obra",
+    "NE": "Nota de encomenda",
+    "OU": "Outros",
+    "OR": "Orçamento",
+    "PF": "Fatura pró-forma",
+    "RC": "Recibo",
+    "RG": "Outro recibo",
+}
+
+_REQUIRED = ("A", "B", "C", "D", "E", "F", "G", "H", "I1", "N", "O", "Q", "R")
+_TAX_KEYS = [f"{letter}{i}" for letter in "IJK" for i in range(1, 9)]
+_MONETARY = {k for k in _TAX_KEYS if not k.endswith("1")} | {"L", "M", "N", "O", "P"}
+# Tamanho máximo de cada campo, pela ordem em que têm de aparecer (ponto 4 da especificação).
+_MAX_LENGTH: dict[str, int] = {
+    **{"A": 9, "B": 30, "C": 12, "D": 2, "E": 1, "F": 8, "G": 60, "H": 70},
+    **{k: 16 if k in _MONETARY else 5 for k in _TAX_KEYS},
+    **{"L": 16, "M": 16, "N": 16, "O": 16, "P": 16, "Q": 4, "R": 4, "S": 65},
+}
+_ORDER = {key: i for i, key in enumerate(_MAX_LENGTH)}
+_AMOUNT = re.compile(r"^-?\d+(\.\d{1,2})?$")
+# ATCUD: código de validação da série (8 ou mais caracteres), hífen e número do documento.
+_ATCUD = re.compile(r"^[A-Z0-9]{8,}-(\d+)$")
+# Identificação do documento no SAF-T(PT): tipo, espaço, série, barra e número.
+_DOCUMENT_ID = re.compile(r"^(\S+) \S+/(\d+)$")
+_TAX_FIELDS = (
+    "exempt_base",
+    "reduced_base",
+    "reduced_vat",
+    "intermediate_base",
+    "intermediate_vat",
+    "normal_base",
+    "normal_vat",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class TaxBreakdown:
+    """IVA de um espaço fiscal (campos I, J ou K)."""
+
+    fiscal_space: str
+    """``PT``, ``PT-AC`` (Açores) ou ``PT-MA`` (Madeira)."""
+    exempt_base: Decimal | None = None
+    reduced_base: Decimal | None = None
+    reduced_vat: Decimal | None = None
+    intermediate_base: Decimal | None = None
+    intermediate_vat: Decimal | None = None
+    normal_base: Decimal | None = None
+    normal_vat: Decimal | None = None
+
+    @property
+    def total_base(self) -> Decimal:
+        parts = (self.exempt_base, self.reduced_base, self.intermediate_base, self.normal_base)
+        return sum((p for p in parts if p is not None), Decimal(0))
+
+    @property
+    def total_vat(self) -> Decimal:
+        parts = (self.reduced_vat, self.intermediate_vat, self.normal_vat)
+        return sum((p for p in parts if p is not None), Decimal(0))
+
+
+@dataclass(frozen=True, slots=True)
+class InvoiceQR:
+    """Os campos de um código QR de fatura, já convertidos."""
+
+    issuer_nif: str
+    buyer_nif: str
+    buyer_country: str
+    document_type: str
+    document_status: str
+    document_date: date
+    document_id: str
+    atcud: str
+    taxes: tuple[TaxBreakdown, ...]
+    total_taxes: Decimal
+    total: Decimal
+    hash_chars: str
+    certificate: str
+    non_taxable: Decimal | None = None
+    stamp_duty: Decimal | None = None
+    withholding: Decimal | None = None
+    other_info: str | None = None
+    fields: dict[str, str] = field(default_factory=dict, compare=False, repr=False)
+    """Os campos tal como vieram, por chave."""
+
+    @property
+    def document_type_name(self) -> str | None:
+        """Nome do tipo de documento (``"Fatura"``), ou ``None`` se for desconhecido."""
+        return DOCUMENT_TYPES.get(self.document_type)
+
+    @property
+    def is_final_consumer(self) -> bool:
+        """``True`` se a fatura não tem NIF do adquirente (consumidor final)."""
+        return self.buyer_nif == "999999990"
+
+    def to_text(self) -> str:
+        """O texto do código QR, pela ordem e com o formato da especificação.
+
+        Valores ``None`` não entram (os campos opcionais sem informação não se criam), e
+        sem espaços fiscais escreve ``I1:0``. Lança :class:`QRCodeError` se algum valor
+        passar o tamanho máximo ou tiver um ``*``, ou se o último acabar em espaço.
+        ``parse(fatura.to_text())`` devolve uma fatura igual a esta.
+        """
+        if len(self.taxes) > 3:
+            raise QRCodeError("Só há três espaços fiscais (campos I, J e K)")
+        fields: dict[str, str | Decimal | None] = {
+            "A": self.issuer_nif,
+            "B": self.buyer_nif,
+            "C": self.buyer_country,
+            "D": self.document_type,
+            "E": self.document_status,
+            "F": self.document_date.strftime("%Y%m%d"),
+            "G": self.document_id,
+            "H": self.atcud,
+        }
+        if not self.taxes:
+            fields["I1"] = "0"
+        for letter, tax in zip("IJK", self.taxes, strict=False):
+            fields[f"{letter}1"] = tax.fiscal_space
+            for i, name in enumerate(_TAX_FIELDS, start=2):
+                fields[f"{letter}{i}"] = getattr(tax, name)
+        fields |= {
+            "L": self.non_taxable,
+            "M": self.stamp_duty,
+            "N": self.total_taxes,
+            "O": self.total,
+            "P": self.withholding,
+            "Q": self.hash_chars,
+            "R": self.certificate,
+            "S": self.other_info,
+        }
+        text = "*".join(
+            f"{key}:{value:.2f}" if isinstance(value, Decimal) else f"{key}:{value}"
+            for key, value in fields.items()
+            if value is not None
+        )
+        if text != text.strip():  # a leitura tira os espaços das pontas
+            raise QRCodeError("O último campo não pode acabar em espaço")
+        _split(text)  # mesmas regras de tamanho e formato que a leitura
+        return text
+
+
+def _split(text: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    for part in text.strip().split("*"):
+        key, sep, value = part.partition(":")
+        if not sep or not key:
+            raise QRCodeError(f"Campo sem o formato CHAVE:valor: {part!r}")
+        if key in fields:
+            raise QRCodeError(f"Campo repetido: {key}")
+        if key not in _MAX_LENGTH:
+            raise QRCodeError(f"Campo desconhecido: {key}")
+        if len(value) > _MAX_LENGTH[key]:
+            raise QRCodeError(
+                f"O campo {key} passa o tamanho máximo ({_MAX_LENGTH[key]} caracteres): {value!r}"
+            )
+        fields[key] = value
+    return fields
+
+
+def _amount(fields: dict[str, str], key: str) -> Decimal | None:
+    raw = fields.get(key)
+    if raw is None:
+        return None
+    if not _AMOUNT.match(raw):
+        raise QRCodeError(f"Valor inválido no campo {key} (usar ponto e até 2 casas): {raw!r}")
+    try:
+        return Decimal(raw)
+    except InvalidOperation as exc:  # pragma: no cover - o regex já o impede
+        raise QRCodeError(f"Valor inválido no campo {key}: {raw!r}") from exc
+
+
+def _taxes(fields: dict[str, str]) -> tuple[TaxBreakdown, ...]:
+    result = []
+    for letter in "IJK":
+        space = fields.get(f"{letter}1")
+        others = [k for k in fields if k.startswith(letter) and k != f"{letter}1"]
+        if space is None:
+            if others:
+                raise QRCodeError(f"Campos {letter}2 a {letter}8 sem o espaço fiscal {letter}1")
+            continue
+        if space == "0":  # documento sem IVA
+            if others:
+                raise QRCodeError(f"{letter}1 é 0 (sem IVA), mas há outros campos {letter}")
+            continue
+        values = {
+            name: _amount(fields, f"{letter}{i}") for i, name in enumerate(_TAX_FIELDS, start=2)
+        }
+        result.append(TaxBreakdown(fiscal_space=space, **values))
+    return tuple(result)
+
+
+def parse(text: str) -> InvoiceQR:
+    """Lê o texto de um código QR de fatura.
+
+    Lança :class:`QRCodeError` se o texto estiver mal formado (campos desconhecidos,
+    repetidos ou acima do tamanho máximo) ou faltarem campos obrigatórios. Aceita
+    valores com menos de duas casas decimais e campos fora de ordem, e não confirma
+    NIFs nem contas: isso fica para :func:`check`.
+    """
+    fields = _split(text)
+    missing = [k for k in _REQUIRED if k not in fields]
+    if missing:
+        raise QRCodeError(f"Faltam campos obrigatórios: {', '.join(missing)}")
+
+    try:
+        document_date = datetime.strptime(fields["F"], "%Y%m%d").date()
+    except ValueError as exc:
+        raise QRCodeError(f"Data inválida no campo F (AAAAMMDD): {fields['F']!r}") from exc
+
+    if len(fields["Q"]) != 4:
+        raise QRCodeError(f"O campo Q tem de ter 4 caracteres do hash: {fields['Q']!r}")
+
+    total_taxes = _amount(fields, "N") or Decimal(0)  # N e O são obrigatórios (vistos acima)
+    total = _amount(fields, "O") or Decimal(0)
+
+    return InvoiceQR(
+        issuer_nif=fields["A"],
+        buyer_nif=fields["B"],
+        buyer_country=fields["C"],
+        document_type=fields["D"],
+        document_status=fields["E"],
+        document_date=document_date,
+        document_id=fields["G"],
+        atcud=fields["H"],
+        taxes=_taxes(fields),
+        non_taxable=_amount(fields, "L"),
+        stamp_duty=_amount(fields, "M"),
+        total_taxes=total_taxes,
+        total=total,
+        withholding=_amount(fields, "P"),
+        hash_chars=fields["Q"],
+        certificate=fields["R"],
+        other_info=fields.get("S"),
+        fields=fields,
+    )
+
+
+def check(invoice: InvoiceQR) -> list[str]:
+    """Problemas de conteúdo numa fatura já lida; lista vazia se estiver tudo certo.
+
+    Confirma a ordem dos campos, as duas casas decimais dos valores, os NIFs, o ATCUD
+    (o número no fim tem de ser o do documento, em G) e as contas: o total de
+    impostos (N) é o IVA mais o selo, e o total (O) é a soma das bases, do não
+    sujeito (L) e dos impostos (N).
+    """
+    problems = []
+    keys = list(invoice.fields)
+    if keys != sorted(keys, key=_ORDER.__getitem__):
+        problems.append("Os campos não estão pela ordem da especificação")
+    problems += [
+        f"O campo {key} devia ter duas casas decimais: {value}"
+        for key, value in invoice.fields.items()
+        if key in _MONETARY and not re.fullmatch(r"-?\d+\.\d\d", value)
+    ]
+    if not is_valid_nif(invoice.issuer_nif):
+        problems.append(f"NIF do emitente inválido: {invoice.issuer_nif}")
+    if invoice.buyer_country == "PT" and not is_valid_nif(invoice.buyer_nif):
+        problems.append(f"NIF do adquirente inválido: {invoice.buyer_nif}")
+
+    problems += _check_atcud(invoice)
+
+    vat = sum((t.total_vat for t in invoice.taxes), Decimal(0))
+    expected_taxes = vat + (invoice.stamp_duty or 0)
+    if expected_taxes != invoice.total_taxes:
+        problems.append(
+            f"Total de impostos (N) é {invoice.total_taxes}, mas IVA + selo dá {expected_taxes}"
+        )
+
+    bases = sum((t.total_base for t in invoice.taxes), Decimal(0))
+    expected_total = bases + (invoice.non_taxable or 0) + invoice.total_taxes
+    if expected_total != invoice.total:
+        problems.append(
+            f"Total (O) é {invoice.total}, mas bases + não sujeito + impostos dá {expected_total}"
+        )
+    return problems
+
+
+def _check_atcud(invoice: InvoiceQR) -> list[str]:
+    document = _DOCUMENT_ID.match(invoice.document_id)
+    if document is None:
+        return [f"Documento (G) sem o formato 'TIPO SÉRIE/NÚMERO': {invoice.document_id}"]
+    problems = []
+    if document[1] != invoice.document_type:
+        problems.append(
+            f"O documento (G) é do tipo {document[1]}, mas o tipo (D) é {invoice.document_type}"
+        )
+    if invoice.atcud == "0":  # sem ATCUD, como era permitido antes de ser obrigatório
+        return problems
+    atcud = _ATCUD.match(invoice.atcud)
+    if atcud is None:
+        problems.append(f"ATCUD (H) sem o formato 'CÓDIGO-NÚMERO': {invoice.atcud}")
+    elif int(atcud[1]) != int(document[2]):
+        problems.append(
+            f"O ATCUD (H) acaba em {atcud[1]}, mas o documento (G) é o n.º {document[2]}"
+        )
+    return problems

faturapt-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: faturapt
+Version: 0.1.0
+Summary: Leitura e validação do código QR das faturas portuguesas (AT) e de NIFs.
+Project-URL: Repository, https://github.com/JoseFerrao20/faturapt
+Project-URL: Changelog, https://github.com/JoseFerrao20/faturapt/blob/main/CHANGELOG.md
+Author: José Ferrão
+License-Expression: MIT
+License-File: LICENSE
+Keywords: atcud,autoridade tributária,fatura,invoice,nif,portugal,qr code
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Portuguese
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: image
+Requires-Dist: pillow>=10; extra == 'image'
+Requires-Dist: zxing-cpp>=3.0; extra == 'image'
+Description-Content-Type: text/markdown
+
+# faturapt
+
+[![CI](https://github.com/JoseFerrao20/faturapt/actions/workflows/ci.yml/badge.svg)](https://github.com/JoseFerrao20/faturapt/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/faturapt)](https://pypi.org/project/faturapt/)
+[![Versões de Python](https://img.shields.io/pypi/pyversions/faturapt)](https://pypi.org/project/faturapt/)
+[![Licença: MIT](https://img.shields.io/badge/licen%C3%A7a-MIT-blue)](LICENSE)
+
+Lê e valida o **código QR das faturas portuguesas** (o que a AT exige desde 2022, Portaria n.º 195/2020) e **NIFs**. Python puro, sem dependências obrigatórias, com tipos.
+
+```python
+>>> import faturapt
+>>> inv = faturapt.parse("A:500000000*B:999999990*C:PT*D:FS*E:N*F:20261015*G:FS 01/1234"
+...                      "*H:JJ3XY2KD-1234*I1:PT*I7:10.00*I8:2.30*N:2.30*O:12.30*Q:Ab1z*R:1234")
+>>> inv.document_type_name, inv.document_date, inv.total
+('Fatura simplificada', datetime.date(2026, 10, 15), Decimal('12.30'))
+>>> inv.is_final_consumer
+True
+>>> faturapt.check(inv)      # NIFs e contas; lista vazia = tudo certo
+[]
+>>> faturapt.nif_type("PT 123 456 789")
+<NifType.INDIVIDUAL: 'pessoa singular'>
+
+```
+
+## Instalar
+
+```bash
+pip install faturapt             # só texto: sem dependências
+pip install 'faturapt[image]'    # também lê fotografias (Pillow e zxing-cpp)
+```
+
+```python
+>>> fatura = faturapt.read_image("talao.jpg")    # doctest: +SKIP
+>>> fatura.total, faturapt.check(fatura)          # doctest: +SKIP
+(Decimal('12.30'), [])
+```
+
+## O que faz
+
+- **`parse(texto)`**: converte o texto do QR num `InvoiceQR` (datas em `date`, valores em `Decimal`, IVA por espaço fiscal: continente, Açores e Madeira). Lança `QRCodeError`, com a mensagem em português, se faltarem campos obrigatórios, houver campos repetidos, desconhecidos ou acima do tamanho máximo, ou valores mal formados.
+- **`check(fatura)`**: devolve os problemas de conteúdo: campos fora de ordem, valores sem duas casas decimais, NIFs inválidos, ATCUD que não acaba no número do documento (G) ou documento (G) de outro tipo que não o D, total de impostos (N) diferente de IVA + selo, ou total (O) diferente de bases + não sujeito + impostos.
+- **`fatura.to_text()`**: o caminho inverso, para quem gera faturas: escreve o texto do QR pela ordem da especificação, com duas casas decimais, e recusa valores acima do tamanho máximo. `parse(fatura.to_text())` devolve sempre a mesma fatura (os testes confirmam-no com o Hypothesis, em faturas geradas ao acaso).
+- **`is_valid_nif`, `nif_type`, `normalize_nif`**: dígito de controlo, prefixos e tipo de contribuinte (pessoa singular, coletiva, condomínio, …). Aceita espaços, pontos e o prefixo `PT`.
+- **`read_image(imagem)`**: encontra o QR da fatura numa fotografia ou digitalização (caminho, `bytes` ou imagem do Pillow) e lê-o com o `parse`. Respeita a orientação EXIF do telemóvel e, se houver outros QR na imagem (um site, uma promoção), escolhe o da fatura. Precisa de `faturapt[image]`.
+- **Linha de comandos**: `faturapt "A:...*B:..."` (ou pelo stdin) ou `faturapt -i talao.jpg` mostra a fatura em JSON. Sai com 0 se estiver tudo certo, com 1 se houver problemas e com 2 se o texto ou a imagem não tiverem um QR válido.
+
+As regras seguem as [especificações técnicas da AT](https://info.portaldasfinancas.gov.pt/pt/apoio_contribuinte/Novas_regras_faturacao/Documents/Especificacoes_Tecnicas_Codigo_QR.pdf) (versão 1.0, agosto de 2020), e os quatro exemplos do documento fazem parte dos testes. O `parse` recusa o que não se consegue ler (campos desconhecidos, repetidos ou acima do tamanho máximo, obrigatórios em falta); o `check` aponta o resto (campos fora de ordem, valores sem duas casas decimais, NIFs e contas).
+
+
+## Campos do QR
+
+| Chave | Campo | `InvoiceQR` |
+|---|---|---|
+| A, B, C | NIF do emitente, NIF e país do adquirente | `issuer_nif`, `buyer_nif`, `buyer_country` |
+| D, E, F, G | Tipo, estado, data e identificação do documento | `document_type`, `document_status`, `document_date`, `document_id` |
+| H | ATCUD | `atcud` |
+| I1–I8, J1–J8, K1–K8 | IVA por espaço fiscal (isento, reduzida, intermédia, normal) | `taxes` (`TaxBreakdown`) |
+| L, M, N, O, P | Não sujeito, selo, total de impostos, total, retenção na fonte | `non_taxable`, `stamp_duty`, `total_taxes`, `total`, `withholding` |
+| Q, R, S | 4 caracteres do hash, n.º do certificado, outras informações | `hash_chars`, `certificate`, `other_info` |
+
+## Desenvolvimento
+
+```bash
+uv sync --all-extras                      # ambiente com as dependências de desenvolvimento e de imagem
+uv run pytest                             # testes, com cobertura mínima de 95 %
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+O CI corre o mesmo em Python 3.10 a 3.14. Para publicar uma versão: atualizar `__version__`, passar as entradas de "Por publicar" do `CHANGELOG.md` para a versão nova, com a data, e criar uma tag `vX.Y.Z`. O workflow `release.yml` publica no PyPI por *trusted publishing* (sem tokens guardados no GitHub).
+
+## Licença
+
+MIT.

faturapt-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+faturapt/__init__.py,sha256=6uF8sGCOsehA0b5NlSJRpTkhC1TO8ypNFT1kbIOxk4s,517
+faturapt/__main__.py,sha256=CaYzSGGYhUSNfWDTYkFP0ni4FMmCMDaf7RLOLAx4C58,1642
+faturapt/image.py,sha256=vGwzvbOYu_IpcJwJ2kuXByLlm26Nn_mGrY5jhSiJoJY,1994
+faturapt/nif.py,sha256=pq6q6aXKgzc1MPb9zPuFMa15VpHl2ZCYougvSfXdmVQ,3298
+faturapt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+faturapt/qr.py,sha256=cBTjs0GdrGoBdN5-TS_pQsk24gSgoAcsgqFEn1DtZUo,12714
+faturapt-0.1.0.dist-info/METADATA,sha256=vyFPtRF6C33oI3Dqjh1BipMniGe18ApImXc6iEjeM04,6312
+faturapt-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+faturapt-0.1.0.dist-info/entry_points.txt,sha256=RmtRQQ-dciS3SxJ9hl_kQGYIcuSsnvf5p3w4bL3hKyU,52
+faturapt-0.1.0.dist-info/licenses/LICENSE,sha256=FD_G0Zs3jAvgOjJgyxQC0kbhv0X2LseaHAySa0LOy40,1070
+faturapt-0.1.0.dist-info/RECORD,,

faturapt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

faturapt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+faturapt = faturapt.__main__:main

faturapt-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José Ferrão
+
+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.