feat: live-validate FR + credit notes; payments, NC redesign, cancel guard

Functional testing against the real Vendus API (test mode, plus one real
FR+NC cycle) surfaced several more wire-shape bugs the mocks hid, and the SDK
now matches the verified behaviour.

Fatura-Recibo (FR):
- create_invoice_receipt now requires `payments` — an FR records payment on
  issue and Vendus rejects it otherwise ("o pagamento deve ser realizado no ato").
- New `Payment` input model and `list_payment_methods()` (+ `PaymentMethod`),
  since payment-method ids are account-specific (GET /v1.0/payments).

Credit note (NC):
- create_credit_note(reference_document_id, reason) redesigned: it GETs the
  original and credits its full set of lines, referencing each via
  `reference_document` (number + row) + the original line id. The previous
  top-level `reference_document_id` was rejected by the API (P001); the method
  had never worked. No more inline items/client/register_id.

Cancel:
- cancel() fetches the document and refuses FT/FR/NC — fiscal documents cannot
  be cancelled ("Não é permitido cancelar este tipo de documentos"); the SDK
  raises ValidationError pointing to create_credit_note.

Robustness:
- _parse_document tolerates unknown type codes (the live account returned `RG`,
  absent from documents/types) via a `DocumentType.UNKNOWN` sentinel; the raw
  code is preserved in raw_response.

Docs/examples updated across EN + PT (FR payments, NC signature, "FT cannot be
cancelled"), README validation matrix refreshed, CLAUDE.md R13 reworked and R16
added with the live-verified wire facts. 79 unit tests + 4 live integration
tests; ruff/mypy/pytest/mkdocs --strict all green.

BREAKING CHANGE: create_invoice_receipt requires payments; create_credit_note
drops register_id/items/client; cancel refuses FT/FR/NC.

Author: bilouro

CHANGELOG.md

@@ -13,9 +13,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `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
+- `Payment` model and `list_payment_methods()` (sync + async) — a Fatura-Recibo now
+  takes `payments=[Payment(method_id=..., amount=...)]`; method ids are account-specific
+- `PaymentMethod` model returned by `list_payment_methods()`
+- `DocumentType.UNKNOWN` — forward-compat sentinel so the SDK does not crash on type
+  codes the API returns but the enum does not model (e.g. `RG`); the raw code stays in
+  `raw_response`
+- Live integration tests (`tests/integration/`, excluded by default): FT and FR in test
+  mode, plus read-only `list_payment_methods`/`list`/`get` against real documents
 - Initial project skeleton
 - `VendusClient` with HTTP Basic Auth
 - `DocumentsService.create_invoice` (sync + async)
@@ -27,7 +32,7 @@ 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)
-- 72 unit tests with `respx` mocks (94% coverage), plus live integration tests
+- 79 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)
@@ -40,7 +45,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
   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.
+  PATCH endpoint has no field for a cancellation reason. It now also fetches the document
+  and **refuses to cancel FT/FR/NC** (fiscal documents cannot be cancelled; reverse them
+  with a credit note), raising `ValidationError` with that guidance.
+- **Breaking:** `create_credit_note(reference_document_id, reason, ...)` no longer takes
+  `register_id`/`items`/`client`. It fetches the original and credits its full set of
+  lines (the original must be a real, retrievable document). The previous signature never
+  worked: Vendus rejected the old top-level `reference_document_id` field.
+- **Breaking:** `create_invoice_receipt(...)` now requires `payments` — an FR records
+  payment on issue and Vendus rejects it otherwise.
 - 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.
@@ -52,6 +65,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
   never succeeded against the live API before this.
 - `cancel` no longer sends `notes` (rejected by the document PATCH endpoint, which
   accepts only `status`/`mode`).
+- Credit notes now build the wire body Vendus accepts — found live: each credit line
+  references the original via `reference_document` (number + row) and the original line
+  id, instead of the rejected top-level `reference_document_id`.
+- `_parse_document` tolerates unknown document type codes instead of raising
+  (the live account returned `RG`, which is absent from the documents/types reference).
 
 ### Quality
 - `mypy --strict` passes with zero errors

CLAUDE.md

@@ -294,16 +294,14 @@ client.documents.create_quote(...)            # OR
 
 Reason: each type has different mandatory/forbidden fields. A credit note **requires** `reference_document_id`; an invoice doesn't. Type-checking and autocomplete are better with dedicated methods.
 
-### R13: Credit Notes Always Reference an Original Document
+### R13: Credit Notes Credit a Real Original Document
 
-Validated locally before any API call:
+`create_credit_note(reference_document_id, reason)` credits the **full** original. Vendus requires each credit line to reference an existing line of the original (`reference_document` = document number + 1-based row) and to carry that line's id, so the SDK **GETs the original** (FT/FR) and replicates its lines. Consequences:
 
-```python
-if reference_document_id is None:
-    raise ValidationError("Credit note requires reference_document_id")
-```
-
-The original document must be a previously-issued invoice (FT) or invoice-receipt (FR). Vendus validates the rest server-side.
+- The original must be **retrievable** → a real document, not a test-mode one (test docs aren't addressable).
+- No inline `items`/`client` — they come from the original.
+- Partial credits are not supported in v0.1.
+- There is **no** top-level `reference_document_id` on the wire — Vendus rejects it (`P001`); the link lives per item.
 
 ### R14: Inline Client Only (v0.1.0)
 
@@ -318,6 +316,17 @@ If the app needs to track Vendus client IDs locally, that is its responsibility.
 
 In Portuguese invoicing, "consumidor final" (final consumer) is represented by omitting the client entirely, NOT by passing `fiscal_id=999999990`. R7 enforces this at validation time.
 
+### R16: Live-verified Wire Facts (do not regress)
+
+These were confirmed against the **real** Vendus API; changing them silently re-breaks the SDK. Each was a bug the respx mocks hid until live-validation caught it:
+
+- **Line items** send `tax_id` (a `TaxCategory` code — `NOR`/`INT`/`RED`/`ISE`/`OUT`), not `tax_rate`; `discount_percentage`, not `discount`; `id` for a product line, not `product_id`. Wrong names → `P001`.
+- **FR (Fatura-Recibo) requires `payments`** — `[{"id": <method_id>, "amount": <gross>}]`. `method_id` is **account-specific**; list it via `list_payment_methods()` (`GET /v1.0/payments`). Missing → "o pagamento deve ser realizado no ato".
+- **Cancel** = `PATCH /documents/{id}` with `{"status":"A"}` only (no reason field). **FT/FR/NC cannot be cancelled** ("Não é permitido cancelar este tipo de documentos") — the SDK fetches the type and refuses, pointing to a credit note.
+- **Test-mode documents** live in a separate space: not retrievable/cancellable via `/documents/{id}` (404 "não existe").
+- **Unknown type codes** (e.g. `RG`, seen live, absent from documents/types) must not crash parsing → `DocumentType.UNKNOWN`, raw code kept in `raw_response`.
+- `tax_authority_id` is **empty in the POST response even for real fiscal documents** (ATCUD/hash mark a doc fiscal), so it is not a reliable test-vs-real discriminator at create time — the series prefix is (`FT T01P…` test vs `FT 01P…` real).
+
 ---
 
 ## How to Add a New Document Type (Future Versions)

README.md

@@ -88,21 +88,14 @@ Do NOT pass `fiscal_id="999999990"` — the SDK rejects it. For final consumer,
 
 ## Credit Notes
 
-A credit note (NC) always references a previously issued document:
+A credit note (NC) credits a previously issued invoice. It is also the only way
+to reverse a fiscal invoice — FT/FR **cannot be cancelled**. The SDK fetches the
+original and credits its full set of lines, so you pass only the id and a reason:
 
 ```python
 credit_note = client.documents.create_credit_note(
-    register_id=1,
     reference_document_id=invoice.id,
     reason="Customer return",
-    items=[
-        DocumentItem(
-            description="Consulting hours (credited)",
-            quantity=Decimal("2"),
-            unit_price=Decimal("75.00"),
-            tax_category=TaxCategory.NORMAL,
-        ),
-    ],
     external_reference="REFUND-2026-001",
 )
 ```
@@ -170,17 +163,17 @@ client = VendusClient.from_env()
 
 ### 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:
+The wire format of every operation is asserted by unit tests (respx mocks), and validated against the real Vendus API — in **test mode** (`mode=tests`, non-fiscal) where possible, and once in real mode for the operations that test mode can't reach:
 
 | 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) |
+| `create_invoice_receipt` (FR) | ✅ | ✅ test mode — requires `payments` |
+| `create_credit_note` (NC) | ✅ | ✅ real mode once (credited a real FR); test-mode originals aren't retrievable |
+| `list_payment_methods` / `list` / `get` | ✅ | ✅ read-only |
+| `cancel` | ✅ | ⚠️ FT/FR/NC can't be cancelled — the SDK refuses them (reverse with a credit 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.
+> Test-mode documents ("Modo de Formação") are non-fiscal and never reported to the AT, but Vendus stores them in a separate space — they can't be retrieved or cancelled via `/documents/{id}`. So credit notes (which must read the original) are validated in real mode, and `cancel` is not live-validated (FT/FR/NC are not cancellable; other types would require voiding a real document).
 
 ## Why This SDK
 

docs/documents/credit-note.md

@@ -2,12 +2,11 @@
 
 ## What it is
 
-A Credit Note (NC) cancels or partially credits a previously issued document (FT or FS). It is the legal mechanism for returns, retroactive discounts, or correcting wrong invoices.
+A Credit Note (NC) credits a previously issued invoice (FT or FR). It is the legal mechanism for returns, refunds, and corrections — and the **only** way to reverse a fiscal invoice, which cannot be cancelled.
 
 - **Always references** an original document (`reference_document_id`)
 - **Reason is mandatory** (`reason`) — required by AT
-- Client should match the original document's client
-- Can be partial (refunding only some items)
+- Credits the **full** original document: the SDK fetches the original and replicates its lines, so the client and amounts come from it (partial credits are not supported in v0.1)
 
 ## Flow
 
@@ -18,10 +17,10 @@ sequenceDiagram
     participant API as Vendus API
     participant AT
 
-    Note over App: Original: client bought 10 hours
-    App->>SDK: create_credit_note(<br/>reference_document_id=12345,<br/>reason="Refund 2h",<br/>items=[2 hours])
-    SDK->>SDK: validate reason + reference_id
-    SDK->>API: POST /v1.1/documents (NC)
+    App->>SDK: create_credit_note(reference_document_id=12345, reason="Refund")
+    SDK->>API: GET /v1.1/documents/12345 (read the original's lines)
+    API-->>SDK: original document
+    SDK->>API: POST /v1.1/documents (NC, crediting each line)
     API->>AT: report NC
     AT-->>API: hash + ATCUD
     API-->>SDK: Document JSON
@@ -31,58 +30,45 @@ sequenceDiagram
 ## Full example
 
 ```python
-from decimal import Decimal
-from vendus import ClientData, DocumentItem, TaxCategory, VendusClient
+from vendus import VendusClient
 
 client = VendusClient.from_env()
 
-# Assume invoice.id was stored from the original issue
+# invoice.id was stored when you issued the original
 original_invoice_id = 12345
 
 nc = client.documents.create_credit_note(
-    register_id=1,
     reference_document_id=original_invoice_id,
-    reason="Client returned 2 consulting hours",
-    client=ClientData(name="Acme Lda", fiscal_id="123456789"),
-    items=[
-        DocumentItem(
-            description="Consulting (credited)",
-            quantity=Decimal("2"),
-            unit_price=Decimal("75.00"),
-            tax_category=TaxCategory.NORMAL,
-        ),
-    ],
+    reason="Client returned the service",
     external_reference="REFUND-2026-001",
 )
 
 print(nc.number)         # "NC 2026/4"
-print(nc.gross_amount)   # Decimal("184.50") — 2 × 75 × 1.23
+print(nc.gross_amount)   # the credited amount
 ```
 
 ## Parameters
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
-| `register_id` | `int` | Yes | POS register ID configured in Vendus |
-| `reference_document_id` | `int` | Yes | ID of the original FT/FS being credited |
+| `reference_document_id` | `int` | Yes | id of the original FT/FR being credited |
 | `reason` | `str` | Yes | Reason for the credit note (required by AT) |
-| `items` | `list[DocumentItem]` | Yes | Items to credit (can be a subset of the original) |
-| `client` | `ClientData \| None` | No | Should match the original document's client |
 | `external_reference` | `str` | No | Enables safe POST retries |
+| `mode` | `DocumentMode \| None` | No | `TESTS` for a non-fiscal test NC |
+
+The client, items and amounts are read from the original document — you do not pass them.
 
 ## Async variant
 
 ```python
 nc = await client.documents.create_credit_note_async(
-    register_id=1,
     reference_document_id=12345,
     reason="...",
-    items=[...],
 )
 ```
 
 ## 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)` instead.
-3. **Consistent client:** if the original was to Final Consumer, the NC should also omit `client`.
+1. **Full credit only (v0.1):** the SDK credits every line of the original. Partial credits (some lines or quantities) are a future addition.
+2. **NC is how you reverse an invoice:** fiscal invoices (FT/FR) **cannot be cancelled** — `cancel()` rejects them. Issue an NC to credit the original instead.
+3. **Real documents only:** the original must be retrievable, so credit notes work on **real** documents, not test-mode ones (which are not addressable via `/documents/{id}`).

docs/documents/credit-note.pt.md

@@ -2,12 +2,11 @@
 
 ## O que é
 
-A Nota de Crédito (NC) anula ou credita parcialmente um documento já emitido (FT ou FS). É o mecanismo legal para devoluções, descontos retroativos, ou correções de faturas erradas.
+Uma Nota de Crédito (NC) credita uma fatura emitida anteriormente (FT ou FR). É o mecanismo legal para devoluções, reembolsos e correções — e a **única** forma de reverter uma fatura fiscal, que não pode ser cancelada.
 
 - **Referencia sempre** um documento original (`reference_document_id`)
 - **Motivo obrigatório** (`reason`) — exigido pela AT
-- O cliente deve coincidir com o do documento original
-- Pode ser parcial (devolução de só alguns itens)
+- Credita o documento original **por inteiro**: o SDK vai buscar o original e replica as suas linhas, por isso o cliente e os valores vêm dele (créditos parciais não são suportados no v0.1)
 
 ## Fluxo
 
@@ -18,11 +17,11 @@ sequenceDiagram
     participant API as Vendus API
     participant AT
 
-    Note over App: Originalmente: cliente comprou 10 horas
-    App->>SDK: create_credit_note(<br/>reference_document_id=12345,<br/>reason="Devolução 2h",<br/>items=[2 horas])
-    SDK->>SDK: validar reason + reference_id
-    SDK->>API: POST /v1.1/documents (NC)
-    API->>AT: comunicar NC
+    App->>SDK: create_credit_note(reference_document_id=12345, reason="Devolução")
+    SDK->>API: GET /v1.1/documents/12345 (lê as linhas do original)
+    API-->>SDK: documento original
+    SDK->>API: POST /v1.1/documents (NC, a creditar cada linha)
+    API->>AT: comunica NC
     AT-->>API: hash + ATCUD
     API-->>SDK: Document JSON
     SDK-->>App: Document(NC)
@@ -31,58 +30,45 @@ sequenceDiagram
 ## Exemplo completo
 
 ```python
-from decimal import Decimal
-from vendus import ClientData, DocumentItem, TaxCategory, VendusClient
+from vendus import VendusClient
 
 client = VendusClient.from_env()
 
-# Assume que invoice.id foi guardado da emissão original
+# invoice.id foi guardado quando emitiste o original
 original_invoice_id = 12345
 
 nc = client.documents.create_credit_note(
-    register_id=1,
     reference_document_id=original_invoice_id,
-    reason="Cliente devolveu 2 horas de consultoria",
-    client=ClientData(name="Acme Lda", fiscal_id="123456789"),
-    items=[
-        DocumentItem(
-            description="Consultoria (creditada)",
-            quantity=Decimal("2"),
-            unit_price=Decimal("75.00"),
-            tax_category=TaxCategory.NORMAL,
-        ),
-    ],
+    reason="Cliente devolveu o serviço",
     external_reference="REFUND-2026-001",
 )
 
 print(nc.number)         # "NC 2026/4"
-print(nc.gross_amount)   # Decimal("184.50") — 2 × 75 × 1.23
+print(nc.gross_amount)   # o valor creditado
 ```
 
 ## Parâmetros
 
 | Parâmetro | Tipo | Obrigatório | Descrição |
 |---|---|---|---|
-| `register_id` | `int` | Sim | ID do POS configurado na Vendus |
-| `reference_document_id` | `int` | Sim | ID da FT/FS original a creditar |
-| `reason` | `str` | Sim | Motivo da NC (exigido pela AT) |
-| `items` | `list[DocumentItem]` | Sim | Itens a creditar (podem ser subset do original) |
-| `client` | `ClientData \| None` | Não | Deve coincidir com o cliente do original |
-| `external_reference` | `str` | Não | Habilita retry seguro do POST |
+| `reference_document_id` | `int` | Sim | id da FT/FR original a creditar |
+| `reason` | `str` | Sim | Motivo da nota de crédito (exigido pela AT) |
+| `external_reference` | `str` | Não | Permite retries seguros do POST |
+| `mode` | `DocumentMode \| None` | Não | `TESTS` para uma NC de teste (não-fiscal) |
+
+O cliente, os itens e os valores são lidos do documento original — não os passas.
 
 ## Variante async
 
 ```python
 nc = await client.documents.create_credit_note_async(
-    register_id=1,
     reference_document_id=12345,
     reason="...",
-    items=[...],
 )
 ```
 
 ## 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)` em alternativa.
-3. **Cliente coerente:** se o original foi a Consumidor Final, a NC também deve omitir `client`.
+1. **Só crédito total (v0.1):** o SDK credita todas as linhas do original. Créditos parciais (algumas linhas/quantidades) ficam para o futuro.
+2. **A NC é como se reverte uma fatura:** faturas fiscais (FT/FR) **não podem ser canceladas** — o `cancel()` rejeita-as. Emite uma NC para creditar o original.
+3. **Apenas documentos reais:** o original tem de ser consultável, por isso as notas de crédito funcionam sobre documentos **reais**, não sobre os de modo teste (que não são endereçáveis via `/documents/{id}`).