Referência API¶
VendusClient¶
vendus.VendusClient
¶
Top-level client. Services are lazy-loaded via properties.
Example
client = VendusClient(api_key="...") invoice = client.documents.create_invoice(...)
from_env(*, env_var='VENDUS_API_KEY', default_mode=None)
classmethod
¶
Construct from an environment variable.
DocumentsService¶
vendus.services.documents.DocumentsService
¶
Bases: BaseService
Issue and manage Vendus documents.
create_invoice(register_id, items, client=None, external_reference=None, mode=None)
¶
Issue an invoice (FT).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
register_id
|
int
|
ID of the POS register configured in Vendus. |
required |
items
|
list[DocumentItem]
|
Line items. |
required |
client
|
ClientData | None
|
Client data — upserted by fiscal_id. Omit for final consumer. |
None
|
external_reference
|
str | None
|
Your internal reference. Required to enable safe POST retries (R3). |
None
|
mode
|
DocumentMode | None
|
Working mode. Pass |
None
|
create_invoice_receipt(register_id, items, payments, client=None, external_reference=None, mode=None)
¶
Issue a Fatura-Recibo (FR).
An FR is an invoice and a receipt in a single document: it bills and acknowledges payment at once. Use it when the client pays immediately (typical for services and freelancers).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
register_id
|
int
|
ID of the POS register configured in Vendus. |
required |
items
|
list[DocumentItem]
|
Line items. |
required |
payments
|
list[Payment]
|
How the document was paid. Required — an FR records
payment on issue, and Vendus rejects it otherwise. Get the
account's method ids from :meth: |
required |
client
|
ClientData | None
|
Client data — omit for final consumer. |
None
|
external_reference
|
str | None
|
Your internal reference. Enables safe POST retries. |
None
|
mode
|
DocumentMode | None
|
|
None
|
create_simplified_invoice(register_id, items, payments, client=None, external_reference=None, mode=None)
¶
Issue a Fatura Simplificada (FS).
A simplified invoice for retail / final-consumer sales (subject to AT
amount limits). Like a Fatura-Recibo, it is paid on issue, so payments
is required. The client is usually omitted (final consumer).
create_receipt(register_id, invoice_numbers, payments, external_reference=None, mode=None)
¶
Issue a Recibo (RG) acknowledging payment of one or more invoices.
A receipt records payment for previously-issued invoices (e.g. an FT) and
carries no line items of its own. Reference the invoices by their document
number (e.g. "FT 2026/123") and provide the payments.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
register_id
|
int
|
ID of the POS register configured in Vendus. |
required |
invoice_numbers
|
list[str]
|
document numbers of the invoices being paid. |
required |
payments
|
list[Payment]
|
how the payment was made (see :meth: |
required |
external_reference
|
str | None
|
Your internal reference. Enables safe POST retries. |
None
|
mode
|
DocumentMode | None
|
|
None
|
create_credit_note(reference_document_id, reason, lines=None, external_reference=None, mode=None)
¶
Issue a credit note (NC) crediting a previously-issued document.
Vendus credits an invoice line by line: each credit line must reference an existing line of the original. The SDK fetches the original (FT/FR) and builds the credit lines from it — the client and amounts come from the original, so you usually pass only the document id and a reason.
The original must be retrievable, i.e. a real (non-test) document; test-mode documents are not addressable and cannot be credited.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
reference_document_id
|
int
|
id of the FT/FR being credited (R13). |
required |
reason
|
str
|
Free-text reason, stored as the document's notes. |
required |
lines
|
list[CreditLine] | None
|
Restrict the credit to specific rows/quantities (partial credit). Omit to credit every still-creditable line of the document. |
None
|
external_reference
|
str | None
|
Your internal reference. Enables safe POST retries. |
None
|
mode
|
DocumentMode | None
|
Working mode for the credit note itself. |
None
|
cancel(document_id)
¶
Cancel (void) a non-fiscal document.
Fiscal invoices (FT/FR) and credit notes (NC) communicated to the AT
cannot be cancelled — Vendus rejects it. To reverse an invoice, issue
a credit note with :meth:create_credit_note. The SDK fetches the document
and raises :class:ValidationError for these types before attempting
any change.
Vendus has no API field for a cancellation reason (the document PATCH endpoint accepts only status/mode), so none is sent.
list_payment_methods()
¶
List the account's configured payment methods (id, title, type).
Use the returned id as Payment.method_id when issuing a
Fatura-Recibo with :meth:create_invoice_receipt.
list_registers()
¶
List the account's registers (caixas) — id, title, working mode.
Registers are read-only via the API (created/configured in the Vendus
backoffice). Use the returned id as register_id when issuing
documents, and check mode to know whether a register is in test or
normal mode.
Modelos¶
vendus.Document
¶
Bases: BaseModel
A document returned by Vendus after creation or lookup.
vendus.DocumentItem
¶
Bases: BaseModel
A line item on a document.
vendus.ClientData
¶
Bases: BaseModel
Inline client data sent with a document.
Two valid shapes:
- With NIF: ClientData(name="Acme Lda", fiscal_id="123456789")
- Name only: ClientData(name="João Silva") — for clients that did not
provide a fiscal_id. Accepted by Vendus on FT and FR.
To invoice a final consumer with NO identification at all, omit the
client argument entirely from create_invoice / create_invoice_receipt.
Vendus upserts by fiscal_id when present. The API does NOT return the
client object in the document response.
vendus.DocumentType
¶
Bases: str, Enum
Vendus document type codes.
UNKNOWN is a forward-compatibility sentinel: the live API can return type
codes this enum does not model (e.g. RG, seen on real accounts but absent
from the documents/types reference). Parsing maps any unmodelled code to
UNKNOWN instead of failing — the exact code is always preserved in
Document.raw_response["type"].
vendus.DocumentStatus
¶
Bases: str, Enum
Normalized status. Mapped from Vendus raw strings by normalize_status().
vendus.TaxExemption
¶
Bases: str, Enum
AT-mandated VAT exemption reason codes (M01-M99).
Use when a line item has tax_category=TaxCategory.EXEMPT and an exemption
reason is required. Full list is published by Autoridade Tributária. The codes
here are the most common; add to this enum as needed.
Exceções¶
vendus.VendusError
¶
Bases: Exception
Base exception for all SDK errors.
Attributes:
| Name | Type | Description |
|---|---|---|
error_code |
the Vendus error code (e.g. |
vendus.ValidationError
¶
Bases: VendusError
The request is invalid — caught locally before the call, or rejected by the
API as malformed (Vendus P001, e.g. a field that is not permitted).
vendus.AuthenticationError
¶
vendus.AuthorizationError
¶
vendus.NotFoundError
¶
vendus.RateLimitError
¶
vendus.APIError
¶
Bases: VendusError
Vendus returned an error response.
Attributes:
| Name | Type | Description |
|---|---|---|
status_code |
HTTP status code from the API. |
|
response_body |
Parsed JSON body if available, else raw text. |
|
error_code |
the Vendus error code from the body, if any. |