Skip to content

Installation & Quickstart

Installation

pip install vendus      # or: uv add vendus

Get your API key

  1. Sign in at www.vendus.pt
  2. Settings → Access → API
  3. Create/copy the API key

The API key identifies the user in Vendus — every document issued via API is attributed to that user.

Configure credentials

Recommended: environment variable or .env file.

export VENDUS_API_KEY="your-key"

from vendus import VendusClient

client = VendusClient.from_env()         # reads VENDUS_API_KEY
# or
client = VendusClient(api_key="...")

Never commit API keys

Add .env to .gitignore. Do not pass API keys as URL parameters or log them.

First invoice

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

client = VendusClient.from_env()

invoice = client.documents.create_invoice(
    register_id=1,                       # POS register ID configured in Vendus
    client=ClientData(
        name="Acme Lda",
        fiscal_id="123456789",
    ),
    items=[
        DocumentItem(
            description="Consulting",
            quantity=Decimal("10"),
            unit_price=Decimal("75.00"), # gross, includes VAT
            tax_category=TaxCategory.NORMAL,
        ),
    ],
    external_reference="ORD-2026-001",   # enables safe POST retries
)

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

Test mode by default

New Vendus accounts have their register in test mode, so documents are non-fiscal until you switch to real mode. Pass VendusClient(api_key=..., default_mode=DocumentMode.NORMAL) (or mode= per call) for real documents. See Configuration.

Reversing a document

Fiscal documents (FT/FR/NC) cannot be cancelled — cancel() rejects them. To reverse an invoice, issue a credit note that credits it:

client.documents.create_credit_note(
    reference_document_id=invoice.id,
    reason="Issued in error",
)

Next steps