fix: align document wire format with the live Vendus API; add test mode

Live validation against the real Vendus API surfaced wire-shape bugs that the
respx mocks hid (create_invoice had never actually worked end-to-end):

- Line items now send `tax_id` (a VAT category — new `TaxCategory` enum) instead
  of the rejected `tax_rate`; `discount_percentage` instead of `discount`; `id`
  instead of `product_id`. The real API returned P001 for the old field names.
- `cancel(document_id)` no longer sends `notes` and drops the `reason` argument —
  the document PATCH endpoint accepts only status/mode (no reason field exists).

Added:
- `mode` parameter (`DocumentMode` enum) on every create_* method to issue
  non-fiscal test-mode documents that Vendus does not report to the AT.
- `Document.tax_authority_id` — empty until the AT is notified.
- Live integration tests (excluded by default): create in test mode and
  read-only list/get against real documents.

Docs:
- Replaced the unsourced "Sandbox" section with a sourced "Testing" section.
- README gains an honest per-operation unit/live validation matrix.
- CLAUDE.md: "Always Honest, Never Assume" rule, eupago-reference.md adopted as
  the build playbook, R1 vocabulary updated, Sandbox TBD resolved.

BREAKING CHANGE: DocumentItem.tax_rate -> tax_category; cancel() no longer takes reason.

Author: bilouro

CHANGELOG.md

@@ -7,6 +7,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 ## [Unreleased]
 
 ### Added
+- `mode` parameter (`DocumentMode` enum: `NORMAL` / `TESTS`) on `create_invoice`,
+  `create_invoice_receipt`, `create_credit_note` (sync + async) — issue non-fiscal
+  test-mode documents that Vendus does not communicate to the AT
+- `Document.tax_authority_id` — the AT-generated id, empty until Vendus reports the
+  document to the AT (lets you confirm a test document was not reported)
+- `TaxCategory` enum (`NORMAL`/`INTERMEDIATE`/`REDUCED`/`EXEMPT`/`OTHER`) for line-item VAT
+- Live integration tests (`tests/integration/`, excluded by default): issue an FT in
+  test mode (asserting `tax_authority_id` is empty) and read-only `list`/`get` against
+  real documents
 - Initial project skeleton
 - `VendusClient` with HTTP Basic Auth
 - `DocumentsService.create_invoice` (sync + async)
@@ -18,13 +27,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Portuguese NIF validation
 - PII redaction filter for logging
 - HttpTransport with conditional POST retries (R3)
-- 69 tests with `respx` mocks (93% coverage)
+- 72 unit tests with `respx` mocks (94% coverage), plus live integration tests
 - Bilingual documentation (PT/EN) with mkdocs-material + i18n
 - 10 runnable examples, including an all-scenarios reference
 - CI workflow (ruff, mypy --strict, pytest on Python 3.9–3.13)
 - Docs auto-deploy to GitHub Pages
 - Issue/PR templates and Dependabot config
 
+### Changed
+- **Breaking:** `DocumentItem.tax_rate` (a `Decimal` percentage) is now `tax_category`
+  (a `TaxCategory` enum). Vendus classifies line-item VAT by category (`tax_id`:
+  NOR/INT/RED/ISE/OUT), not by a numeric rate — the rate is defined by the category in
+  the merchant's Vendus configuration.
+- **Breaking:** `cancel(document_id)` no longer takes a `reason` — the Vendus document
+  PATCH endpoint has no field for a cancellation reason.
+- Docs: replaced the "Sandbox" section with a sourced "Testing" section. Vendus has
+  no separate sandbox host; testing is done via document-level test mode. Corrects a
+  prior unsourced claim that every call creates real fiscal documents.
+
+### Fixed
+- Line items now send the field names the real Vendus API actually accepts — found by
+  live validation, which returned `P001` for the old names: `tax_id` (was `tax_rate`),
+  `discount_percentage` (was `discount`), `id` (was `product_id`). `create_invoice` had
+  never succeeded against the live API before this.
+- `cancel` no longer sends `notes` (rejected by the document PATCH endpoint, which
+  accepts only `status`/`mode`).
+
 ### Quality
 - `mypy --strict` passes with zero errors
 - `ruff check` / `ruff format` clean

CLAUDE.md

@@ -8,6 +8,47 @@ Unofficial Python SDK for the [Vendus](https://www.vendus.pt) invoicing API (Por
 
 Vendus is an AT-certified (Autoridade Tributária) invoicing/POS SaaS. The Vendus backend handles all communication with the AT (SAF-T, ATCUD, QR code, document hash). This SDK talks to Vendus; Vendus talks to AT. The SDK never communicates with the AT directly.
 
+## Working Principle: Always Honest, Never Assume (non-negotiable)
+
+This rule overrides convenience. It applies to code, comments, docs, commit messages, and every reply to the user.
+
+- **State only what is verified.** If something is not confirmed, say so explicitly and label it as an assumption or unknown — never present a guess or general knowledge as established fact.
+- **Cite the source for any claim about the Vendus API or AT behavior.** No source → mark it `TBD` in the code/docs and flag it for verification. Do not write unsourced assertions into user-facing docs.
+- **When asked "how do we know X?"**, if there is no verified source, say so plainly instead of rationalizing after the fact.
+- **When uncertain, verify or ask before acting.** Don't fill gaps with plausible-sounding details.
+- **No contradictions between artifacts.** If the docs claim something the code/CLAUDE.md still lists as `TBD`, that is a bug — resolve it, don't paper over it.
+
+> Origin: the docs once stated "Vendus has no public sandbox" as fact, with no cited source, while CLAUDE.md still listed sandbox as `TBD — investigate`. That unsourced assertion is exactly what this rule forbids.
+
+## Build Playbook — `eupago-reference.md` is the foundation
+
+The canonical playbook for building this SDK is [`eupago-reference.md`](eupago-reference.md) at the repo root — the distilled engineering discipline from the sibling `eupago-python` SDK. **Read it before any substantial work.** It is the *why*; the rules in this file are the Vendus-specific *how*.
+
+- **R1–R15 below are the Vendus application of that playbook.** Adapt, don't copy: where the Vendus domain demands a different choice, diverge **deliberately and document it** — e.g. R3's conditional POST retries vs. the playbook's blanket no-retry, because Vendus accepts `external_reference` as a dedup anchor.
+- The playbook's identity, architecture, naming, money/PII/validation and quality rules are already encoded as R1–R15 and the Architecture section. The two disciplines below are imported here explicitly because they are **not** yet encoded elsewhere in this file and this project has already been bitten by their absence.
+
+### Live-validation discipline (`eupago-reference.md` §4, §8) — non-negotiable
+
+Two test layers, both required:
+
+| Layer | Tool | Runs | Purpose |
+|---|---|---|---|
+| Unit | `pytest` + `respx` | every commit / CI | guard the **exact wire body**, validation, sync/async parity |
+| Live | `pytest -m integration` | on demand | prove the SDK works against the **real Vendus API** end-to-end |
+
+- Unit tests **assert the exact JSON sent on the wire**, not just the return value — that is how latent field-name/shape bugs are caught (`body = json.loads(route.calls[0].request.content); assert body == {...}`).
+- Live tests live in `tests/integration/`, are marked `@pytest.mark.integration` (excluded from the default `pytest` run), and **auto-skip** when `VENDUS_API_KEY` is absent — no false failures on machines without creds.
+- **One live test per operation**, exercising the full loop (SDK → Vendus → parse). Run them against the **test-mode register configured in `.env`** (`VENDUS_REGISTER_ID`, a register whose `mode` is `tests`) so live tests issue **non-fiscal** documents that are never reported to the AT. Concretely: assert a created test document comes back with an empty `tax_authority_id` (that field is only set once Vendus has communicated the document to the AT).
+- **"If you didn't run it against the real Vendus API, it isn't done."** The Vendus `.doc` reference pages describe what *should* happen; verify the actual wire shape live before claiming an operation works. This is the operational form of the *Always Honest, Never Assume* rule above.
+
+### Honesty in status reporting (`eupago-reference.md` §4, §8.1, §10.3)
+
+- README / CHANGELOG / roadmap use a **per-operation matrix** (Unit ✅ / Live ✅), never a blanket "service done".
+- Never mark a row **Done** without a live test — or a live test that **skips with a documented reason**. A skipped-with-reason test is honest; a green test that never hit the API is a trap.
+- When the upstream docs turn out wrong or incomplete: fix the SDK, add a unit test asserting the **corrected** wire body, then the live test passes — and record the divergence (with the Vendus error it fixed) in the CHANGELOG.
+
+For situations not covered here — webhooks, multiple identifiers for one resource, form-vs-JSON bodies, operations that don't return a field the docs promise — consult `eupago-reference.md` §7–§8 when they arise.
+
 ## Scope (v0.1.0 — MVP)
 
 - Issue invoices (FT)
@@ -102,6 +143,7 @@ The Vendus API uses Portuguese-influenced naming (`fiscal_id`, `amount_gross`).
 | Document number | `number` | `number` | `str` |
 | Document type | `type` | `type` | `DocumentType` enum |
 | Subtype | `subtype` | `subtype` | `str` |
+| Working mode | `mode` | `mode` | `DocumentMode` enum |
 | Date issued | `date` | `date` | `datetime` |
 | Local time | `local_time` | `local_time` | `datetime` |
 | System time | `system_time` | `system_time` | `datetime` |
@@ -110,13 +152,16 @@ The Vendus API uses Portuguese-influenced naming (`fiscal_id`, `amount_gross`).
 | Tax amount | `tax_amount` | (derived) | `Decimal` |
 | AT hash | `hash` | `hash` | `str` |
 | ATCUD | `atcud` | `atcud` | `str` |
+| AT document ID | `tax_authority_id` | `tax_authority_id` | `str` |
 | QR code data | `qrcode` | `qrcode` | `str` |
 | External reference | `external_reference` | `external_reference` | `str` |
 | Reference document | `reference_document_id` | (credit note ref) | `int` |
 | Item description | `description` | `title` | `str` |
 | Item quantity | `quantity` | `qty` | `Decimal` |
 | Item unit price | `unit_price` | `gross_price` | `Decimal` |
-| Tax rate | `tax_rate` | `tax_rate` | `Decimal` |
+| Item discount % | `discount` | `discount_percentage` | `Decimal` |
+| Product id | `product_id` | `id` | `int` |
+| Tax category | `tax_category` | `tax_id` | `TaxCategory` enum |
 | Tax exemption | `tax_exemption` | `tax_exemption` | `TaxExemption` enum |
 
 **When adding a new resource:** look at its API fields. Use the table. If a new concept appears, add it here and use it consistently.
@@ -308,7 +353,7 @@ async def create_receipt_async(self, ...) -> Document: ...
 ### Base URLs
 - Production: `https://www.vendus.pt/ws/`
 - Spain: `https://www.vendus.es/ws/`
-- Sandbox: TBD — investigate during v0.1 dev
+- Sandbox: **none.** Vendus has no separate sandbox host. Testing is done via a document-level test mode — pass `mode=tests` on a create call, or use a register configured in `tests` mode (new accounts default to this). Test documents are non-fiscal and not communicated to the AT (their `tax_authority_id` stays empty). Sources: [documents.doc](https://www.vendus.pt/ws/v1.1/documents.doc), [registers.doc](https://www.vendus.pt/ws/v1.1/registers.doc), [Modo de Formação/Testes](https://www.vendus.cv/ajuda/modo-formacao-testes/). Not yet live-verified: whether a per-request `mode=tests` overrides a `normal` register.
 
 ### Endpoint Versions
 - Documents: `v1.1` (`/ws/v1.1/documents/`)

README.md

@@ -27,7 +27,7 @@ Requires Python 3.9+. No additional dependencies beyond [httpx](https://www.pyth
 
 ```python
 from decimal import Decimal
-from vendus import VendusClient, ClientData, DocumentItem
+from vendus import ClientData, DocumentItem, TaxCategory, VendusClient
 
 client = VendusClient(api_key="your-api-key")
 
@@ -40,7 +40,7 @@ invoice = client.documents.create_invoice(
             description="Consulting hours",
             quantity=Decimal("10"),
             unit_price=Decimal("75.00"),  # gross (includes tax)
-            tax_rate=Decimal("23"),
+            tax_category=TaxCategory.NORMAL,
         ),
     ],
     external_reference="ORD-2026-001",   # enables safe POST retries
@@ -100,7 +100,7 @@ credit_note = client.documents.create_credit_note(
             description="Consulting hours (credited)",
             quantity=Decimal("2"),
             unit_price=Decimal("75.00"),
-            tax_rate=Decimal("23"),
+            tax_category=TaxCategory.NORMAL,
         ),
     ],
     external_reference="REFUND-2026-001",
@@ -168,6 +168,20 @@ client = VendusClient.from_env()
 | Guia de Transporte | GT | — | v0.2 |
 | Nota de Débito | ND | — | v0.2 |
 
+### Validation status
+
+The wire format of every operation is asserted by unit tests (respx mocks). Live validation runs against the real Vendus API in **test mode** (`mode=tests`) — non-fiscal documents that are never reported to the AT:
+
+| Operation | Unit | Live |
+|---|:-:|---|
+| `create_invoice` (FT) | ✅ | ✅ test mode — non-fiscal, `tax_authority_id` empty |
+| `create_invoice_receipt` (FR) | ✅ | ⚠️ not yet run live |
+| `create_credit_note` (NC) | ✅ | ⚠️ not yet run live |
+| `get` / `list` | ✅ | ✅ read-only, against real documents |
+| `cancel` | ✅ | ⚠️ not live-validated (see note) |
+
+> Test-mode documents ("Modo de Formação") are non-fiscal and never reported to the AT. Vendus stores them in a separate space, so they can't be retrieved or cancelled via `/documents/{id}`. Live `get`/`list` are validated read-only against real documents; `cancel` is not live-validated because voiding a real fiscal document is destructive.
+
 ## Why This SDK
 
 - **Fully typed** — `mypy --strict` passes, `py.typed` marker included. Full autocomplete in VS Code and PyCharm.

docs/documents/credit-note.md

@@ -32,7 +32,7 @@ sequenceDiagram
 
 ```python
 from decimal import Decimal
-from vendus import VendusClient, ClientData, DocumentItem
+from vendus import ClientData, DocumentItem, TaxCategory, VendusClient
 
 client = VendusClient.from_env()
 
@@ -49,7 +49,7 @@ nc = client.documents.create_credit_note(
             description="Consulting (credited)",
             quantity=Decimal("2"),
             unit_price=Decimal("75.00"),
-            tax_rate=Decimal("23"),
+            tax_category=TaxCategory.NORMAL,
         ),
     ],
     external_reference="REFUND-2026-001",
@@ -84,5 +84,5 @@ nc = await client.documents.create_credit_note_async(
 ## Notes
 
 1. **Full vs partial NC:** if refunding the whole amount, replicate all items. For partial refunds, include only the items/quantities to credit.
-2. **NC is not cancellation:** an NC **credits** the value but keeps the original document. To fully void, use `client.documents.cancel(id, reason)` instead.
+2. **NC is not cancellation:** an NC **credits** the value but keeps the original document. To fully void, use `client.documents.cancel(id)` instead.
 3. **Consistent client:** if the original was to Final Consumer, the NC should also omit `client`.

docs/documents/credit-note.pt.md

@@ -32,7 +32,7 @@ sequenceDiagram
 
 ```python
 from decimal import Decimal
-from vendus import VendusClient, ClientData, DocumentItem
+from vendus import ClientData, DocumentItem, TaxCategory, VendusClient
 
 client = VendusClient.from_env()
 
@@ -49,7 +49,7 @@ nc = client.documents.create_credit_note(
             description="Consultoria (creditada)",
             quantity=Decimal("2"),
             unit_price=Decimal("75.00"),
-            tax_rate=Decimal("23"),
+            tax_category=TaxCategory.NORMAL,
         ),
     ],
     external_reference="REFUND-2026-001",
@@ -84,5 +84,5 @@ nc = await client.documents.create_credit_note_async(
 ## Notas
 
 1. **NC total vs parcial:** se devolves o total, replica todos os itens. Se devolves uma parte, inclui só os itens/quantidades a creditar.
-2. **Não é cancelamento:** uma NC **credita** o valor mas mantém o documento original. Para cancelar completamente, usa `client.documents.cancel(id, reason)` em alternativa.
+2. **Não é cancelamento:** uma NC **credita** o valor mas mantém o documento original. Para cancelar completamente, usa `client.documents.cancel(id)` em alternativa.
 3. **Cliente coerente:** se o original foi a Consumidor Final, a NC também deve omitir `client`.

docs/documents/index.md

@@ -45,7 +45,7 @@ The SDK validates locally **before** hitting the API:
 
 - **Portuguese NIF:** mod 11 algorithm (rejects bad check digits)
 - **NIF 999999990:** explicitly rejected
-- **Items:** at least one, `quantity > 0`, `0 ≤ tax_rate ≤ 100`
+- **Items:** at least one, `quantity > 0`, a `tax_category` (NORMAL/INTERMEDIATE/REDUCED/EXEMPT/OTHER)
 - **Credit Note:** requires `reference_document_id` and `reason`
 - **Cancellation:** requires `reason`
 

docs/documents/index.pt.md

@@ -45,7 +45,7 @@ O SDK valida localmente **antes** de tocar na API:
 
 - **NIF português:** algoritmo mod 11 (rejeita check digits errados)
 - **NIF 999999990:** explicitamente rejeitado
-- **Items:** pelo menos um, `quantity > 0`, `0 ≤ tax_rate ≤ 100`
+- **Items:** pelo menos um, `quantity > 0`, uma `tax_category` (NORMAL/INTERMEDIATE/REDUCED/EXEMPT/OTHER)
 - **Nota de Crédito:** exige `reference_document_id` e `reason`
 - **Cancelamento:** exige `reason`
 

docs/documents/invoice-receipt.md

@@ -12,7 +12,7 @@ The Invoice-Receipt (FR) is **an invoice and a receipt in one document**: it bil
 
 ```python
 from decimal import Decimal
-from vendus import VendusClient, ClientData, DocumentItem
+from vendus import ClientData, DocumentItem, TaxCategory, VendusClient
 
 client = VendusClient.from_env()
 
@@ -24,7 +24,7 @@ fr = client.documents.create_invoice_receipt(
             description="Consulting session (paid on the spot)",
             quantity=Decimal("1"),
             unit_price=Decimal("90.00"),
-            tax_rate=Decimal("23"),
+            tax_category=TaxCategory.NORMAL,
         ),
     ],
     external_reference="FR-2026-001",
@@ -73,5 +73,5 @@ fr = await client.documents.create_invoice_receipt_async(
 ## Notes
 
 1. **Immediate payment:** FR assumes payment happens at issue time. If you bill on credit, use `create_invoice` (FT) and issue the receipt (RC) when the client pays — RC comes in a future version.
-2. **Cancellation:** same API (`client.documents.cancel(id, reason)`).
+2. **Cancellation:** same API (`client.documents.cancel(id)`).
 3. **Credit note:** an FR can be credited via `create_credit_note` referencing the FR's `id`.

docs/documents/invoice-receipt.pt.md

@@ -12,7 +12,7 @@ A Fatura-Recibo (FR) é **fatura e recibo num só documento**: factura a venda *
 
 ```python
 from decimal import Decimal
-from vendus import VendusClient, ClientData, DocumentItem
+from vendus import ClientData, DocumentItem, TaxCategory, VendusClient
 
 client = VendusClient.from_env()
 
@@ -24,7 +24,7 @@ fr = client.documents.create_invoice_receipt(
             description="Sessão de consultoria (paga na hora)",
             quantity=Decimal("1"),
             unit_price=Decimal("90.00"),
-            tax_rate=Decimal("23"),
+            tax_category=TaxCategory.NORMAL,
         ),
     ],
     external_reference="FR-2026-001",
@@ -73,5 +73,5 @@ fr = await client.documents.create_invoice_receipt_async(
 ## Notas
 
 1. **Pagamento imediato:** a FR pressupõe que o pagamento ocorre no momento da emissão. Se faturas a crédito, usa `create_invoice` (FT) e emite o recibo (RC) quando o cliente pagar — RC chega numa versão futura.
-2. **Cancelamento:** mesma API (`client.documents.cancel(id, reason)`).
+2. **Cancelamento:** mesma API (`client.documents.cancel(id)`).
 3. **Nota de crédito:** uma FR pode ser creditada via `create_credit_note` referenciando o `id` da FR.

docs/documents/invoice.md

@@ -32,7 +32,7 @@ sequenceDiagram
 
 ```python
 from decimal import Decimal
-from vendus import VendusClient, ClientData, DocumentItem
+from vendus import ClientData, DocumentItem, TaxCategory, VendusClient
 
 client = VendusClient.from_env()
 
@@ -52,7 +52,7 @@ invoice = client.documents.create_invoice(
             description="Consulting",
             quantity=Decimal("10"),
             unit_price=Decimal("75.00"),
-            tax_rate=Decimal("23"),
+            tax_category=TaxCategory.NORMAL,
         ),
     ],
     external_reference="ORD-2026-001",
@@ -105,7 +105,7 @@ invoice = await client.documents.create_invoice_async(
 
 ## VAT-exempt items
 
-When `tax_rate=0`, AT requires an exemption code (M01-M99):
+When `tax_category=TaxCategory.EXEMPT`, AT requires an exemption code (M01-M99):
 
 ```python
 from vendus import DocumentItem, TaxExemption
@@ -114,7 +114,7 @@ DocumentItem(
     description="Education service",
     quantity=Decimal("1"),
     unit_price=Decimal("100.00"),
-    tax_rate=Decimal("0"),
+    tax_category=TaxCategory.EXEMPT,
     tax_exemption=TaxExemption.M07,  # Exempt Article 9.º CIVA
 )
 ```
@@ -132,13 +132,10 @@ Common codes:
 ## Cancel an invoice
 
 ```python
-cancelled = client.documents.cancel(
-    document_id=invoice.id,
-    reason="Wrong client",
-)
+cancelled = client.documents.cancel(document_id=invoice.id)
 ```
 
-AT requires `reason`. Cancellation is non-idempotent — do not pass max_retries > 0.
+Vendus has no API field for a cancellation reason, so none is sent. Cancellation is non-idempotent — do not pass max_retries > 0.
 
 ## Notes