vendus Python SDK

SDK Python para a Vendus, plataforma portuguesa de faturação e POS certificada pela AT.

SDK da comunidade

Este é um projeto open-source independente, não afiliado nem endossado pela Vendus.

Quickstart

from decimal import Decimal
from vendus import ClientData, DocumentItem, TaxCategory, VendusClient

client = VendusClient(api_key="a-tua-key")

invoice = client.documents.create_invoice(
    register_id=1,
    client=ClientData(name="Acme Lda", fiscal_id="123456789"),
    items=[
        DocumentItem(
            description="Horas de consultoria",
            quantity=Decimal("10"),
            unit_price=Decimal("75.00"),
            tax_category=TaxCategory.NORMAL,
        ),
    ],
)

print(invoice.number)   # "FT 2026/123"
print(invoice.atcud)    # código de comunicação à AT
print(invoice.qrcode)   # payload do QR code da AT

Tipos de documentos suportados

Documento	Código	Método	Estado
Fatura	FT	client.documents.create_invoice	✅
Fatura Simplificada	FS	client.documents.create_simplified_invoice	✅
Fatura-Recibo	FR	client.documents.create_invoice_receipt	✅
Recibo	RG	client.documents.create_receipt	✅
Nota de Crédito	NC	client.documents.create_credit_note	✅

Porquê este SDK?

• Sync + Async — mesmo client, sufixo _async para variantes assíncronas
• 100% tipado — mypy --strict, autocomplete total no IDE
• Decimal para dinheiro — nunca float. Precisão ao cêntimo, exigida pela AT
• Retries seguros — GET retenta automaticamente; POST só com external_reference (evita documento fiscal duplicado)
• NIF validado localmente — algoritmo mod 11, falha antes de tocar na API
• Redação de PII em logs — fiscal_id, email, telefone, morada
• AT é opaco — Vendus comunica com a AT; o SDK nunca fala diretamente com a AT

Próximos passos

• Instalação

  ---

  Instalar e configurar em 2 minutos

  Começar

• Documentos

  ---

  Qual tipo usar? Guia de decisão

  Documentos

• Receitas

  ---

  Guias para FastAPI, Flask, Django

  Receitas

• Erros

  ---

  Hierarquia de exceções e como tratar

  Erros