Ir para o conteúdo

Instalação e Quickstart

Instalação

pip install vendus      # ou: uv add vendus

Obter API key

  1. Inicia sessão em www.vendus.pt
  2. Definições → Acessos → API
  3. Cria/copia a API key

A API key identifica o utilizador na Vendus — todos os documentos emitidos via API ficam atribuídos a esse utilizador.

Configurar credenciais

Recomendado: variável de ambiente ou ficheiro .env.

export VENDUS_API_KEY="a-tua-key"

from vendus import VendusClient

client = VendusClient.from_env()         # lê VENDUS_API_KEY
# ou
client = VendusClient(api_key="...")

Nunca commits API keys

O .env deve estar no .gitignore. Não passes API keys como parâmetro de URL nem as registes em logs.

Primeira fatura

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

client = VendusClient.from_env()

invoice = client.documents.create_invoice(
    register_id=1,                       # ID do POS configurado na Vendus
    client=ClientData(
        name="Acme Lda",
        fiscal_id="123456789",
    ),
    items=[
        DocumentItem(
            description="Consultoria",
            quantity=Decimal("10"),
            unit_price=Decimal("75.00"), # bruto, com IVA incluído
            tax_category=TaxCategory.NORMAL,
        ),
    ],
    external_reference="ORD-2026-001",   # ativa retry seguro em POST
)

print(f"Fatura {invoice.number}")
print(f"Total: {invoice.gross_amount} EUR")
print(f"ATCUD: {invoice.atcud}")
print(f"QR: {invoice.qrcode}")

Modo teste por defeito

Contas Vendus novas têm a caixa em modo teste, por isso os documentos são não-fiscais até passares para modo real. Usa VendusClient(api_key=..., default_mode=DocumentMode.NORMAL) (ou mode= por chamada) para documentos reais. Ver Configuração.

Reverter um documento

Documentos fiscais (FT/FR/NC) não podem ser cancelados — o cancel() recusa-os. Para reverter uma fatura, emite uma nota de crédito que a credita:

client.documents.create_credit_note(
    reference_document_id=invoice.id,
    reason="Emitida por erro",
)

Próximos passos