@beel_es/sdk 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -0,0 +1,244 @@
+# Changelog
+
+All notable changes to the BeeL Node.js SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.2.0] - 2026-09-28
+
+Contract resynced with the API as it runs in production today and types regenerated.
+
+### Added
+- **The VeriFactu status webhook says which record changed.** The `verifactu.status.updated`
+  payload (`WebhookEventDataVeriFactuStatusUpdated`) carries `operation`: `REGISTRATION` for
+  the invoice's registration, `VOID` for the cancellation of a voided invoice. The API always
+  sends it. The enum is exported as `VeriFactuRecordOperation`.
+
+### Changed
+- **`province` is optional in the `Address` you send.** It is only required for an address in
+  Spain (`country_code` `ES`, or no country); the API rejects a Spanish address without it with
+  a `422`. Code that sets it still compiles.
+- Recurring invoices: `payment_term_days` documents how the due date of each generated invoice
+  is computed.
+
+## [2.1.0] - 2026-09-28
+
+### Fixed
+- **Automatic retries now happen.** `maxRetries`, `retryDelayMs` and `maxRetryDelayMs` had no
+  effect: the retry hook only ran when `fetch` itself rejected, and then ignored the error, so
+  no request was ever retried. Retries now run in a wrapper around `fetch`, and only when
+  repeating the request cannot apply it twice: `429` (after `Retry-After`) for any method;
+  `409 IDEMPOTENCY_KEY_PROCESSING` with the same key; `5xx` and network errors for `GET` and
+  for requests that carry an `Idempotency-Key`. A `5xx` the API replays for a key
+  (`Idempotency-Replay: true`) is not retried. Every wait is capped at `maxRetryDelayMs`.
+- **A retry reuses the call's `Idempotency-Key`.** The previous retry code, had it run, set a
+  new key on each attempt, which could create a second invoice. One call now sends one key on
+  every attempt.
+- **`autoIdempotencyKey: false` is honoured.** It was declared but never read.
+- **Typed errors keep the API's error code.** `BeeLConflictError`, `BeeLValidationError` and the
+  other subclasses replaced `error.code` with a generic value, so codes such as
+  `INVOICE_DUPLICATE_EXTERNAL_REFERENCE` were lost. They are now in the new `apiCode` field
+  (`code` is unchanged). `BeeLConflictError` also carries `details`.
+- **Request fields the API defaults are optional in the generated types.** Fields such as a
+  line's `line_type` and `discount_percentage`, or `options.issue_directly`, were typed as
+  required because they have a default. On schemas that only travel in requests they are now
+  optional, as the contract says; response types are unchanged.
+- **`InvoiceBuilder` can set the tax of its lines.** `addLine` never set `main_tax`, which the
+  API requires on every normal line. New `mainTax(tax)` sets it for the lines added after it,
+  and `addLine` takes an optional per-line `mainTax`.
+
+### Added
+- `company.invoices.createOnce(body)`: creates a standard or simplified invoice once per
+  `external_ref` — looks it up first, and after a `409 INVOICE_DUPLICATE_EXTERNAL_REFERENCE`
+  or an unknown outcome returns the invoice that exists. Safe to call again after any error.
+- Per-call `RequestOptions` on every `company.invoices` method: `idempotencyKey`, `signal`
+  and `timeoutMs` (the timeout covers the automatic retries).
+- `beel.catalogs.identity()` (`GET /v1/me/identity`): the credential's `account_id`, the
+  starting point to list its companies.
+- `BeeLErrorCodes`, `EXTERNAL_REF_UNIQUE_INVOICE_TYPES` and the types `RequestOptions`,
+  `CreateInvoiceOnceRequest`, `CreateInvoiceOnceParams`, `ExternalRefUniqueInvoiceType`,
+  `BeeLErrorCode`.
+- A typed Markdown reference in `docs/reference/` (one page per resource, one anchor per
+  method, an index of every method) and `llms.txt`, generated from the source and the
+  contract with `npm run docs:reference` and shipped in the package. `npm test` fails when
+  it is stale or a public method lacks JSDoc.
+- README: a *Common tasks* section, and the exact retry and idempotency semantics.
+
+## [2.0.0] - 2026-09-27
+
+Contract resynced with the API as it runs in production today (public contract 1.9.0) and
+types regenerated. The major bump is because several **generated types narrow or lose
+fields**, not because any method changed name: most integrations compile unchanged.
+
+### Changed (BREAKING)
+- **Series need a `document_type`.** Creating a series (`company.series.create`, and the
+  series in an account import) now requires `document_type`: each series numbers one kind
+  of document.
+- **Equivalence surcharge and IRPF rates follow the current tables.** `EquivalenceSurchargePercentage`
+  is `0 | 0.26 | 0.5 | 0.62 | 1 | 1.4 | 1.75 | 5.2` (the old `0.625` is `0.62`).
+  `IrpfPercentage` adds `2.8`, `6`, `7.6` and `9.5` and is now a `number`, so a line's
+  `irpf_rate` is no longer typed as an integer.
+- **`verifactu.chaining_hash` is gone from the invoice.** The API no longer returns it.
+- **`accounts.provision()` returns what the API returns**: `ProvisionAccountResult`
+  (`account_id`, `status`, `claim_token`, `claim_url`, `claim_link_already_issued`), not a
+  `ManagedAccountSummary`. The old type described fields the response never carried. Call
+  `beel.accounts.get(accountId)` for the summary.
+- **Webhook event types are usable.** Every generated event type (`InvoiceIssuedEvent`, …)
+  collapsed to `never`, so `if (event.type === '...')` narrowed to nothing. They are now
+  plain types with `type` as the literal the API sends, and a real event has `test` absent
+  or `false`: check `if (event.test) return;` before narrowing on `type`.
+  `WebhookEventEnvelope` types `type` as a string literal union instead of the enum.
+- Schemas the contract dropped are no longer in `components`: `IgicPercentage`,
+  `IpsiPercentage`, `IrpfCategory`, `OtherTaxPercentage`, `VatCategory`.
+- `phone` on company and customer updates is typed by `PhoneInput` (the input rules); the
+  `Phone` returned in responses no longer carries a minimum length or pattern.
+
+### Added
+- `company.invoices.createSimplifiedExchange()` — issues a full invoice in exchange for one or
+  more issued simplified invoices (`POST .../invoices/simplified-exchanges`). The simplified
+  invoices become `VOIDED` with `void_cause: 'EXCHANGED'`; the new invoice lists them in
+  `replaced_invoice_ids`.
+- `company.invoices.verifactuRecords(invoiceId)` — the VeriFactu records of an invoice
+  (registration and, if voided, cancellation), each with its own status.
+- Voids take `issued_in_error` (required as `true` once the invoice was sent or paid).
+- Correctives take `circumstance_date`, `recipient` and `recipient_is_business`.
+- Exemption reasons `ISP_ART_84_2_B`, `_C`, `_D` and `_G`; tax rates and surcharges carry
+  `valid_from` / `valid_until`; tax configuration returns `withholding_options`.
+- Recurring invoices return `is_failing` and `last_generated_scheduled_date`; their history
+  entries carry `type`, `origin`, `reason` and who requested them.
+- Webhooks `invoice.pdf.generated` and `invoice.schedule_failed`: `InvoicePdfGeneratedEvent`,
+  `InvoiceScheduleFailedEvent` and their `WebhookEventData*` types, included in `WebhookEvent`.
+  `VeriFactuSubmissionStatus` now includes `PENDING`, sent when the record is submitted.
+- Error codes documented by the contract for the flows above (for example
+  `VOID_REQUIRES_ISSUED_IN_ERROR`, `CORRECTIVE_OUT_OF_TIME`, `SIMPLIFIED_NOT_EXCHANGEABLE`,
+  `EXCHANGE_INVOICE_NOT_VOIDABLE`, `SERIES_DOCUMENT_TYPE_LOCKED_HAS_INVOICES`). They reach
+  you as `error.code` on the typed errors, as before.
+- `npm run typecheck`.
+
+### Fixed
+- The `beel.raw` example called `GET /v1/companies/{company_id}/logo`, which does not exist
+  (the logo is only `PUT` and `DELETE`); it now uses `GET .../invoice-customization`.
+
+## [1.3.0] - 2026-09-17
+
+### Added
+- **Payment connections per NIF**: `beel.company(id).paymentConnections` — list, start an
+  authorization, update and disconnect. A connection is addressed by **its own UUID**, not by
+  the provider slug: a NIF can hold several connections of the same provider. The slug is only
+  sent when starting an authorization.
+- **Payment events of a connection**: `...paymentConnections.events(connectionId)` — list with
+  the full filter set, read one, and the five recovery levers for a charge that did not invoice:
+  `retry`, `draft` (builds a draft invoice to review before issuing), `resolve`, `discard`
+  and `restore`.
+- **Fiscal configuration per company**: `beel.company(id).verifactuConfiguration` and
+  `.taxConfiguration`. These are the canonical replacements the `beel.configuration` JSDoc
+  already pointed at, which did not exist until now. In VeriFactu, `enabled` is the only
+  writable field: whether an invoice reaches AEAT is a fact of the NIF resolved at issue time.
+- **Invoice schedule**: `beel.company(id).invoices.schedule` — one `set()` and one `clear()`
+  replace the legacy `schedule`, `reschedule` and `unschedule` calls.
+- **Invoice derivation**: `beel.company(id).invoices.derive()`, the canonical form of `duplicate`.
+- **Catalogs and preferences**: `beel.catalogs.taxTypes()`, `.invoiceCustomizationOptions()`
+  and `.updateMe()`, on their canonical paths instead of the deprecated `/v1/configuration/*`.
+- **`beel.raw`**: the typed client underneath, for any endpoint the SDK does not wrap yet. A new
+  route reaches the generated types as soon as the contract is synced, but its ergonomic wrapper
+  is written by hand — so without this you had to wait for a release to call it. Same
+  authentication, retries and `Idempotency-Key`, and still typed: a path, parameter or body the
+  contract does not have will not compile.
+- `check:coverage` guard: a ratchet that fails the build when the contract grows a live
+  operation the SDK does not wrap. The current set is recorded in
+  `scripts/coverage-baseline.json`, so it does not block today, but the contract can no longer
+  grow unnoticed.
+
+### Fixed
+- `beel.accounts.scope(id).companies.list()` read the collection as a bare array with the
+  pagination beside it. The contract wraps it (`data.companies` + `data.pagination`), so the
+  call did not type-check against the current API. Its public return shape is unchanged.
+- CI: the auto-regenerate workflow depended on a `branch` field the backend never sends, so
+  only the spec sync ever ran and the generated types were never refreshed. It now regenerates
+  and runs the contract guards on every sync that brings changes.
+- `npm publish` ran neither the tests nor the contract guards; `prepublishOnly` now does.
+
+### Changed
+- OpenAPI contract synced with the published API (the previous copy was five weeks behind);
+  types regenerated.
+
+## [1.2.0] - 2026-08-11
+
+### Added
+- **Accounts (multi-account provisioning)**: `beel.accounts` — list/get/provision managed
+  accounts, plus `beel.accounts.scope(accountId)` for members (roles and per-company grants),
+  invitations, account-scoped webhook subscriptions (secret rotation, deliveries, retries, test),
+  companies under an account, usage counters, claim tokens, ownership transfer and access level.
+- **Company scope (multi-NIF)**: `beel.company(companyId)` — invoices (full lifecycle: create,
+  issue, void, corrective, convert proforma, status, PDF, send), customers (incl. bulk), products,
+  series (incl. typed defaults seeding), recurring invoices, fiscal summary and issuing readiness.
+  All operations address the company in the path; no session focus needed.
+- Webhook event catalog expanded from the contract: `invoice.issued`, `invoice.voided`,
+  `invoice.email.sent`, `recurring_invoice.paused`, `account.claimed`, `company.created`,
+  `representation.signed` and test events, all exported and included in `WebhookEvent`.
+- `check:deprecated` drift guard: fails the build if the SDK wraps an operation the OpenAPI
+  contract marks `deprecated: true` without a matching `@deprecated` tag (or vice versa).
+
+### Changed
+- OpenAPI contract synced from backend `develop` (v1.7.1); types regenerated.
+- Invoice lines now require `line_type` (`NORMAL` | `SUPLIDO`); `InvoiceBuilder.addLine()`
+  defaults to `NORMAL`.
+
+### Deprecated
+- `VeriFactuStatusUpdatedData` and `VeriFactuStatus` type names, renamed in the contract to
+  `WebhookEventDataVeriFactuStatusUpdated` and `VeriFactuSubmissionStatus`. Deprecated aliases
+  are kept so existing imports keep compiling.
+- The whole session-focus surface (`beel.invoices`, `beel.customers`, `beel.products`,
+  `beel.series`, `beel.configuration`, `beel.downloadPdf`), matching the contract. Use the
+  company-scoped equivalents on `beel.company(companyId)`.
+
+## [Unreleased]
+
+## [2.1.0] - 2026-09-28
+
+### Added
+- Initial release of the BeeL Node.js SDK
+- Full TypeScript support with auto-generated types from OpenAPI spec
+- Modular architecture with separate resource classes (Invoices, Customers, Products)
+- HTTP client with automatic retry logic and exponential backoff
+- Idempotency support for safe request retries
+- Comprehensive error handling with custom error classes
+- Support for all public API endpoints:
+  - Invoices (create, list, retrieve, update, delete, issue, send, mark as paid, download PDF)
+  - Customers (CRUD operations)
+  - Products (CRUD operations)
+  - Configuration (tax settings, VeriFactu, invoice series)
+  - NIF validation
+  - Business Profiles (multi-NIF support)
+  - Public metrics
+
+### Configuration Options
+- `apiKey` - Your BeeL API key (required)
+- `baseUrl` - API base URL (default: `https://app.beel.es/api`)
+- `timeout` - Request timeout in milliseconds (default: 30000)
+- `maxRetries` - Maximum retry attempts for GET requests (default: 3)
+- `retryDelay` - Initial retry delay in milliseconds (default: 1000)
+
+### Error Types
+- `BeelError` - Base error class
+- `BeelAuthenticationError` - 401 authentication errors
+- `BeelValidationError` - 400/422 validation errors
+- `BeelNotFoundError` - 404 not found errors
+- `BeelRateLimitError` - 429 rate limit errors
+- `BeelTimeoutError` - Request timeout errors
+- `BeelNetworkError` - Network/connection errors
+
+## [1.0.0] - 2026-02-28
+
+### Added
+- Initial public release
+- Complete SDK generated from OpenAPI specification
+- TypeScript type definitions
+- Comprehensive README with usage examples
+- MIT License
+
+[Unreleased]: https://github.com/beel-es/beel-node-sdk/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/beel-es/beel-node-sdk/releases/tag/v1.0.0

package/README.md

@@ -8,13 +8,17 @@ Official Node.js/TypeScript SDK for the [BeeL API](https://beel.es) — Spanish
 
 **Node.js 18+. Single dependency ([openapi-fetch](https://openapi-ts.dev/openapi-fetch/)).**
 
+**Reading this from `node_modules`?** Everything you need is in Markdown next to this file:
+this README for common tasks, [`docs/reference/README.md`](docs/reference/README.md) for every
+resource and method (HTTP operation, parameters, return shape, errors), and
+[`llms.txt`](llms.txt) as a short index. You do not need to read `dist/index.d.ts`.
+
 ## Features
 
-- **Full TypeScript types** auto-generated from OpenAPI spec
-- **Automatic retries** with exponential backoff on 429 and 5xx
-- **Auto idempotency keys** on every POST request
-- **Typed errors** — catch `BeeLNotFoundError` instead of checking status codes
-- **PDF download** as Buffer
+- **Full TypeScript types** generated from the OpenAPI contract, and a [typed Markdown reference](docs/reference/README.md)
+- **Automatic retries** on 429, 5xx and network errors — only when repeating the request cannot apply it twice
+- **Idempotency keys** on every POST, reused by that call's retries; `createOnce` for invoices you must never duplicate
+- **Typed errors** — catch `BeeLNotFoundError` instead of checking status codes, read the API's `apiCode`
 - **Webhook signature verification** with HMAC-SHA256
 - **Instance-based client** — multiple API keys, no global state
 - **ESM + CommonJS**
@@ -25,30 +29,204 @@ Official Node.js/TypeScript SDK for the [BeeL API](https://beel.es) — Spanish
 npm install @beel_es/sdk
 ```
 
-## Quick Start
+## Common tasks
+
+Every example is typed: the request bodies are `components['schemas'][...]` of the contract,
+which you can import with `import type { components } from '@beel_es/sdk'`.
+
+### Set up the client
 
 ```typescript
 import { BeeL } from '@beel_es/sdk';
 
-const beel = new BeeL({ apiKey: 'beel_sk_live_...' });
+// beel_sk_test_* → sandbox (VeriFactu test mode, no quota), beel_sk_live_* → production
+const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY! });
+```
 
-// Address a company (NIF) explicitly — the recommended multi-NIF surface
-const company = beel.company('company-uuid');
+### Find the company id
+
+Every invoice belongs to a company (a NIF), addressed by its UUID — not by the NIF itself.
+Your API key tells you its account; the account lists its companies:
+
+```typescript
+const { account_id } = await beel.catalogs.identity();
+const { companies } = await beel.account(account_id).companies.list({ search: 'B12345678' });
+
+const company = beel.company(companies[0].id!); // keep this id in your configuration
+```
 
-// Create a draft invoice
-const invoice = await company.invoices.create({
+### Create and issue a standard invoice
+
+A create makes a `DRAFT`; `issue` numbers it and submits it to VeriFactu. Or do both in one
+call with `options.issue_directly`.
+
+```typescript
+import type { components } from '@beel_es/sdk';
+
+type CreateInvoiceRequest = components['schemas']['CreateInvoiceRequest'];
+
+const body: CreateInvoiceRequest = {
   type: 'STANDARD',
-  recipient: { customer_id: 'customer-uuid' },
+  external_ref: 'ORD-2026-0042', // your order id: unique per live invoice, searchable
+  recipient: { customer_id: 'customer-uuid' }, // or the recipient's data inline
+  lines: [
+    {
+      description: 'Consulting',
+      quantity: 10,
+      unit_price: 85.5,
+      main_tax: { type: 'IVA', percentage: 21, regime_key: '01' }, // required on every line
+    },
+  ],
+};
+
+const draft = await company.invoices.create(body);
+const issued = await company.invoices.issue(draft.id);
+console.log(issued.invoice_number); // e.g. "A-2026/0001"
+
+// Or in one call:
+const invoice = await company.invoices.create({ ...body, options: { issue_directly: true } });
+```
+
+### Create a simplified invoice (ticket)
+
+For sales up to the legal limit without identifying the customer. The recipient may be empty
+and must not carry a NIF.
+
+```typescript
+const ticket = await company.invoices.create({
+  type: 'SIMPLIFIED',
+  external_ref: 'TICKET-2026-0815',
+  recipient: {},
   lines: [
-    { line_type: 'NORMAL', description: 'Consulting', quantity: 1, unit_price: 100, discount_percentage: 0 },
+    { description: 'Menú del día', quantity: 2, unit_price: 14.5, main_tax: { type: 'IVA', percentage: 10, regime_key: '01' } },
   ],
+  options: { issue_directly: true },
 });
+```
 
-console.log(invoice.id); // UUID assigned immediately
+If the customer later asks for a full invoice, exchange it:
+`company.invoices.createSimplifiedExchange({ simplified_invoice_ids: [ticket.id], recipient: { customer_id } })`.
 
-// Issue it to assign an invoice number and trigger VeriFactu
-const issued = await company.invoices.issue(invoice.id);
-console.log(issued.invoice_number); // e.g. "A-2026/0001"
+### Correct an issued invoice
+
+An issued invoice is never edited. If the operation happened but the invoice is wrong, issue a
+corrective; if it was issued by mistake, void it.
+
+```typescript
+// Partial: only the difference (here, a discount granted after the sale)
+const corrective = await company.invoices.createCorrective(issued.id, {
+  rectification_type: 'PARTIAL',
+  rectification_code: 'R1',
+  reason: 'Discount agreed with the customer after the sale',
+  lines: [
+    { description: 'Discount', quantity: -1, unit_price: 50, main_tax: { type: 'IVA', percentage: 21, regime_key: '01' } },
+  ],
+});
+
+// Total: cancels everything still invoiced on the original (no lines)
+await company.invoices.createCorrective(issued.id, {
+  rectification_type: 'TOTAL',
+  rectification_code: 'R1',
+  reason: 'Order cancelled by agreement with the customer before delivery',
+});
+
+// Issued by mistake (a test, an accidental duplicate):
+await company.invoices.void(issued.id, { reason: 'Duplicate invoice issued by mistake', issued_in_error: true });
+```
+
+A corrective is not covered by the one-invoice-per-`external_ref` rule (it carries the order
+reference of the invoice it corrects), so `createOnce` does not create correctives. To retry one
+safely, list by `rectified_invoice_id` (`company.invoices.list({ rectified_invoice_id })`) before
+sending it again, or pass the same `idempotencyKey` (see below).
+
+### Find invoices by your own reference
+
+```typescript
+const { invoices } = await company.invoices.list({ external_ref: 'ORD-2026-0042' });
+const invoice = invoices.find((i) => i.type === 'STANDARD' || i.type === 'SIMPLIFIED');
+```
+
+At most one live (not deleted) standard or simplified invoice can hold a given `external_ref`
+in each environment: a second create answers `409` with `apiCode`
+`INVOICE_DUPLICATE_EXTERNAL_REFERENCE`.
+
+### Read the VeriFactu status
+
+AEAT answers asynchronously: a successful issue means *accepted for submission*.
+
+```typescript
+const current = await company.invoices.get(invoiceId);
+current.verifactu?.submission_status; // 'PENDING' | 'ACCEPTED' | 'REJECTED' | 'VOIDED' | 'NOT_SUBMITTED'
+current.verifactu?.qr_url;            // AEAT verification URL, from submission on
+current.verifactu?.error_code;        // AEAT's code when it reported a problem
+
+// The records themselves (registration, then cancellation if voided)
+const records = await company.invoices.verifactuRecords(invoiceId);
+
+// Everything AEAT rejected
+const { invoices: rejected } = await company.invoices.list({ verifactu_status: 'REJECTED' });
+```
+
+To be told instead of polling, subscribe a webhook to `verifactu.status.updated` (see
+[Webhooks](#webhooks)).
+
+### Retries, idempotency and never duplicating an invoice
+
+What the client does on its own (defaults: `maxRetries: 3`, `autoIdempotencyKey: true`):
+
+| Situation | Automatic retry? |
+|---|---|
+| `429` rate limit | Yes, after `Retry-After`, any method. The API refused the request unprocessed. |
+| `409 IDEMPOTENCY_KEY_PROCESSING` | Yes, with the same key: the first request is still running. |
+| `5xx` or network error on a `GET` | Yes, with exponential backoff. |
+| `5xx` or network error on a `POST` | Yes, **with the same `Idempotency-Key`**: if the first attempt took effect, the API replays its answer instead of running it again. A `5xx` the API replays (`Idempotency-Replay: true`) is final and is not retried. |
+| `5xx` or network error on a `PUT`/`PATCH`/`DELETE`, or a `POST` sent without a key | No. |
+| Any other `4xx` | No. |
+
+- **One call, one key.** Every `POST` gets an `Idempotency-Key` (a UUID) once, and every
+  automatic retry of that call reuses it. An automatic retry never creates a second invoice.
+- **A new call is a new key.** If `create()` finally throws a `5xx` or a network error, the
+  outcome is unknown: the invoice may exist. Calling `create()` again sends a new key and can
+  duplicate it. Do not do that.
+- **The API stores the answer of a key for 24 hours** (a `2xx` or a `5xx`; a `4xx` is not
+  stored, so the corrected request can reuse the key). Retrying with the same key after a `5xx`
+  returns the same `5xx`.
+
+The recommended pattern: give the invoice your order id as `external_ref`, and create it with
+`createOnce`. It looks the reference up first, creates only if nothing holds it, and when the
+create fails with an unknown outcome or a `409 INVOICE_DUPLICATE_EXTERNAL_REFERENCE`, it returns
+the invoice that does exist. Calling it again after any error is safe.
+
+```typescript
+const invoice = await company.invoices.createOnce({
+  type: 'STANDARD',
+  external_ref: order.id,
+  recipient: { customer_id: order.customerId },
+  lines: [{ description: 'Order', quantity: 1, unit_price: 100, main_tax: { type: 'IVA', percentage: 21, regime_key: '01' } }],
+  options: { issue_directly: true },
+});
+```
+
+If you manage keys yourself, persist one per operation and pass it on every attempt:
+
+```typescript
+await company.invoices.create(body, undefined, { idempotencyKey: `order-${order.id}`, timeoutMs: 15_000 });
+```
+
+Errors keep the API's own code in `apiCode` (`code` stays the generic class code for backward
+compatibility):
+
+```typescript
+import { BeeLConflictError, BeeLErrorCodes } from '@beel_es/sdk';
+
+try {
+  await company.invoices.create(body);
+} catch (error) {
+  if (error instanceof BeeLConflictError && error.apiCode === BeeLErrorCodes.INVOICE_DUPLICATE_EXTERNAL_REFERENCE) {
+    // someone already created it: look it up by external_ref
+  }
+  throw error;
+}
 ```
 
 ## Companies (multi-NIF)
@@ -157,6 +335,9 @@ It is the same client the resources use — authentication, retries and `Idempot
 still apply — and it stays typed: a path, parameter or body the contract does not have
 will not compile. What you give up is the sugar and the naming stability of the wrappers.
 
+Error handling is the SDK's too: a non-2xx answer is **thrown** as a typed error (below), so a
+`raw` call never resolves with openapi-fetch's `{ error }` — `data` is always the success body.
+
 ## Accounts (managed accounts, members & webhooks)
 
 For integrators managing several accounts (provisioning, gestorías, platforms):
@@ -257,21 +438,27 @@ try {
 
 | Error class | Status | When |
 |---|---|---|
-| `BeeLAuthError` | 401, 403 | Invalid or missing API key |
+| `BeeLAuthError` | 401, 403 | Invalid or missing API key, or no access to the resource |
 | `BeeLNotFoundError` | 404 | Resource doesn't exist |
-| `BeeLValidationError` | 422 | Invalid data |
-| `BeeLConflictError` | 409 | Duplicate (e.g. same NIF) |
-| `BeeLRateLimitError` | 429 | Too many requests (auto-retried) |
-| `BeeLApiError` | 5xx | Server error (auto-retried) |
+| `BeeLValidationError` | 422 | Invalid data or a business rule |
+| `BeeLConflictError` | 409 | Duplicate (`external_ref`, NIF…) or an `Idempotency-Key` conflict |
+| `BeeLRateLimitError` | 429 | Too many requests (retried automatically first) |
+| `BeeLApiError` | 400, 5xx | Bad request, or a server error (retried when safe) |
+
+Every error carries `statusCode`, `apiCode` (the API's `error.code`, e.g.
+`INVOICE_DUPLICATE_EXTERNAL_REFERENCE`), `code` (a generic code per class), `details` and
+`requestId` — quote the last one when you contact support. See
+[docs/reference/errors.md](docs/reference/errors.md).
 
 ## Automatic Retries
 
-429 and 5xx errors are retried with exponential backoff. Client errors (400, 401, 404, 422) are never retried.
+See [Retries, idempotency and never duplicating an invoice](#retries-idempotency-and-never-duplicating-an-invoice)
+for exactly what is retried. Tune it with:
 
 ```typescript
 const beel = new BeeL({
   apiKey: 'beel_sk_live_...',
-  maxRetries: 5,          // default: 3
+  maxRetries: 5,          // default: 3 (0 disables retries)
   retryDelayMs: 1000,     // default: 500
   maxRetryDelayMs: 60000, // default: 30000
 });
@@ -334,6 +521,7 @@ const customer = CustomerBuilder.create()
 
 const invoice = InvoiceBuilder.create()
   .forCustomer('customer-uuid')
+  .mainTax({ type: 'IVA', percentage: 21, regime_key: '01' }) // required on every line
   .addLine('Service A', 5, 100.0)
   .addLine('Service B', 3, 150.0)
   .metadata({ stripe_id: 'pi_abc123' })
@@ -359,12 +547,15 @@ const beel = new BeeL({
   maxRetries: 3,                       // Default
   retryDelayMs: 500,                   // Default
   maxRetryDelayMs: 30000,              // Default
+  autoIdempotencyKey: true,            // Default
 });
 ```
 
 ## Documentation
 
-Full API docs: [docs.beel.es](https://docs.beel.es)
+- SDK reference: [docs/reference/README.md](docs/reference/README.md) — every resource and
+  method, generated from the source and the contract (`npm run docs:reference`).
+- API docs: [docs.beel.es](https://docs.beel.es)
 
 ## License