@beel_es/sdk 2.0.0 → 2.2.0

package/docs/reference/customers.md

@@ -0,0 +1,91 @@
+<!-- Generated by `npm run docs:reference` from the SDK source and openapi/public-api.yaml. Do not edit. -->
+
+# `beel.customers` — `CustomersResource`
+
+[Reference index](README.md)
+
+> **Deprecated.** The contract deprecates the session-focus routes. Use `beel.company(companyId).customers` instead.
+
+Customers of the focused company, on the flat `/v1/customers` routes.
+
+## Methods
+
+| Method | HTTP | Summary |
+|---|---|---|
+| [`beel.customers.list(params?)`](#customers-list) | `GET /v1/customers` | List customers with optional filters and pagination. |
+| [`beel.customers.create(body)`](#customers-create) | `POST /v1/customers` | Create a new customer. |
+| [`beel.customers.get(id)`](#customers-get) | `GET /v1/customers/{customer_id}` | Get a customer by ID. |
+| [`beel.customers.update(id, body)`](#customers-update) | `PUT /v1/customers/{customer_id}` | Update a customer. |
+| [`beel.customers.deactivate(id)`](#customers-deactivate) | `DELETE /v1/customers/{customer_id}` | Deactivate (soft-delete) a customer. |
+
+<a id="customers-list"></a>
+### `list(params?)`
+
+List customers with optional filters and pagination.
+
+- **HTTP:** `GET /v1/customers` · operation `listCustomers` · scopes `customers:read` · **deprecated in the contract**
+- **Parameters:**
+  - `params?: ListParams` — Filters and pagination.
+- **Returns:** The page of `customers` and its `pagination`. Response `200` `data`: `{ customers: Customer[]; pagination: Pagination }`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+**Example**
+
+```typescript
+const { customers, pagination } = await beel.customers.list({ search: 'Acme', limit: 10 });
+```
+
+<a id="customers-create"></a>
+### `create(body)`
+
+Create a new customer.
+
+- **HTTP:** `POST /v1/customers` · operation `createCustomer` · scopes `customers:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `body: components['schemas']['CreateCustomerRequest']` — Legal name, NIF and address.
+- **Returns:** The created customer. Response `201` `data`: `Customer`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+**Example**
+
+```typescript
+const customer = await beel.customers.create({
+  legal_name: 'Acme SL',
+  nif: 'B12345678',
+  address: { street: 'Calle Mayor', number: '1', postal_code: '28001', city: 'Madrid', province: 'Madrid', country: 'Spain', country_code: 'ES' },
+});
+```
+
+<a id="customers-get"></a>
+### `get(id)`
+
+Get a customer by ID.
+
+- **HTTP:** `GET /v1/customers/{customer_id}` · operation `getCustomer` · scopes `customers:read` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Customer UUID.
+- **Returns:** The customer. Response `200` `data`: `Customer`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="customers-update"></a>
+### `update(id, body)`
+
+Update a customer. Only provided fields are changed.
+
+- **HTTP:** `PUT /v1/customers/{customer_id}` · operation `updateCustomer` · scopes `customers:write` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Customer UUID.
+  - `body: components['schemas']['UpdateCustomerRequest']` — Fields to change.
+- **Returns:** The updated customer. Response `200` `data`: `Customer`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="customers-deactivate"></a>
+### `deactivate(id)`
+
+Deactivate (soft-delete) a customer.
+
+- **HTTP:** `DELETE /v1/customers/{customer_id}` · operation `deleteCustomer` · scopes `customers:write` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Customer UUID.
+- **Returns:** Response `200` `data`: `{ message: string }`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `409` `BeeLConflictError` · `429` `BeeLRateLimitError`

package/docs/reference/errors.md

@@ -0,0 +1,72 @@
+<!-- Generated by `npm run docs:reference` from the SDK source and openapi/public-api.yaml. Do not edit. -->
+
+# Errors
+
+[Reference index](README.md)
+
+Every resource method rejects with one of these classes when the API answers non-2xx. A
+network failure is thrown as the platform's own `fetch` error. `beel.raw` calls go through
+the same client, so they also throw these errors instead of returning `{ error }`.
+
+<a id="beelapierror"></a>
+## `BeeLApiError` extends `Error`
+
+Base error for every non-2xx answer of the BeeL API. The client throws it (or one of its
+subclasses) from any resource method; a network failure is thrown as the platform's own
+`fetch` error instead.
+
+| Field | Type | Description |
+|---|---|---|
+| `statusCode` | `number` | HTTP status of the response. |
+| `code` | `string` | Stable code of the error class. On the base class it is the API's `error.code`; the subclasses keep a fixed generic value (`CONFLICT`, `NOT_FOUND`…) for backward compatibility. Read `apiCode` for the API's specific code. |
+| `apiCode` | `string` | The `error.code` the API answered with, verbatim — for example `INVOICE_DUPLICATE_EXTERNAL_REFERENCE`. Equal to `code` when the response did not carry one. See `BeeLErrorCodes` for the codes this SDK reacts to. |
+| `details` | `Record<string, string>` | `error.details` of the response, when the API sent any. |
+| `requestId` | `string` | `meta.request_id` of the response. Quote it when you contact support. |
+
+<a id="beelratelimiterror"></a>
+## `BeeLRateLimitError` extends `BeeLApiError`
+
+`429`: rate limit exceeded. Retried automatically, see `maxRetries`.
+
+| Field | Type | Description |
+|---|---|---|
+| `retryAfterSeconds` | `number` | Seconds the API asked to wait before the next request. |
+
+<a id="beelvalidationerror"></a>
+## `BeeLValidationError` extends `BeeLApiError`
+
+`422`: validation or business rule error. `details` names the offending fields.
+
+<a id="beelautherror"></a>
+## `BeeLAuthError` extends `BeeLApiError`
+
+`401` / `403`: the API key is missing or invalid, or lacks access to the resource.
+
+<a id="beelnotfounderror"></a>
+## `BeeLNotFoundError` extends `BeeLApiError`
+
+`404`: the resource does not exist.
+
+<a id="beelconflicterror"></a>
+## `BeeLConflictError` extends `BeeLApiError`
+
+`409`: conflict — for example `INVOICE_DUPLICATE_EXTERNAL_REFERENCE` or an
+`Idempotency-Key` reused with another body. Branch on `BeeLApiError.apiCode`.
+
+<a id="webhookverificationerror"></a>
+## `WebhookVerificationError` extends `Error`
+
+Webhook verification error
+
+<a id="beelerrorcodes"></a>
+## `BeeLErrorCodes`
+
+`error.code` values of the API that the SDK itself reacts to. Compare them with
+`BeeLApiError.apiCode`. The full catalogue lives in the API reference
+(https://docs.beel.es); these are the ones this package has behaviour for.
+
+| Code | Meaning |
+|---|---|
+| `INVOICE_DUPLICATE_EXTERNAL_REFERENCE` | `409`: a live standard or simplified invoice with the same `external_ref` already exists in this environment. Look it up with `invoices.list({ external_ref })`. |
+| `IDEMPOTENCY_KEY_PROCESSING` | `409`: the first request with this `Idempotency-Key` is still being processed. Retry with the same key after `Retry-After`; the client does so automatically. |
+| `IDEMPOTENCY_KEY_MISMATCH` | `409`: the `Idempotency-Key` was already used with a different body. Use a new key. |

package/docs/reference/invoice-builder.md

@@ -0,0 +1,149 @@
+<!-- Generated by `npm run docs:reference` from the SDK source and openapi/public-api.yaml. Do not edit. -->
+
+# `InvoiceBuilder`
+
+[Reference index](README.md)
+
+Fluent builder for the body of `invoices.create`. It builds the request object only; send
+it with `beel.company(companyId).invoices.create(builder.build())`.
+
+The API requires a `main_tax` on every `NORMAL` line (`422 LINE_MAIN_TAX_REQUIRED`
+otherwise): set it once with `mainTax`, or per line in `addLine`.
+
+**Example**
+
+```typescript
+const request = InvoiceBuilder.create()
+  .forCustomer('customer-uuid')
+  .mainTax({ type: 'IVA', percentage: 21, regime_key: '01' })
+  .addLine('Consulting services', 10, 85.5)
+  .build();
+const invoice = await beel.company(companyId).invoices.create(request);
+```
+
+## Methods
+
+| Method | HTTP | Summary |
+|---|---|---|
+| [`InvoiceBuilder.create()`](#invoice-builder-create) | — | Start a new builder. |
+| [`InvoiceBuilder.type(type)`](#invoice-builder-type) | — | Set the invoice type. |
+| [`InvoiceBuilder.forCustomer(customerId)`](#invoice-builder-for-customer) | — | Invoice a registered customer. |
+| [`InvoiceBuilder.operationDate(date)`](#invoice-builder-operation-date) | — | Date the operation took place, when it differs from the issue date. |
+| [`InvoiceBuilder.dueDate(date)`](#invoice-builder-due-date) | — | Payment due date. |
+| [`InvoiceBuilder.mainTax(tax)`](#invoice-builder-main-tax) | — | Main tax applied to every line added with `addLine` after this call, unless the line passes its own. |
+| [`InvoiceBuilder.addLine(description, quantity, unitPrice, discountPercentage?, mainTax?)`](#invoice-builder-add-line) | — | Add a `NORMAL` line. |
+| [`InvoiceBuilder.addLineObject(line)`](#invoice-builder-add-line-object) | — | Add a line exactly as given — any line type or pricing mode. |
+| [`InvoiceBuilder.notes(notes)`](#invoice-builder-notes) | — | Notes printed on the invoice. |
+| [`InvoiceBuilder.series(id)`](#invoice-builder-series) | — | Number the invoice in this series instead of the default one. |
+| [`InvoiceBuilder.metadata(data)`](#invoice-builder-metadata) | — | Your own key/value pairs, filterable when listing. |
+| [`InvoiceBuilder.build()`](#invoice-builder-build) | — | Build the request body. |
+
+<a id="invoice-builder-create"></a>
+### `create()`
+
+Start a new builder.
+
+- **Returns:** An empty `STANDARD` invoice builder.
+
+<a id="invoice-builder-type"></a>
+### `type(type)`
+
+Set the invoice type. Default: `STANDARD`.
+
+- **Parameters:**
+  - `type: InvoiceType` — `STANDARD`, `SIMPLIFIED` or `PROFORMA` (correctives use `createCorrective`).
+- **Returns:** This builder.
+
+<a id="invoice-builder-for-customer"></a>
+### `forCustomer(customerId)`
+
+Invoice a registered customer.
+
+- **Parameters:**
+  - `customerId: string` — Customer UUID.
+- **Returns:** This builder.
+
+<a id="invoice-builder-operation-date"></a>
+### `operationDate(date)`
+
+Date the operation took place, when it differs from the issue date.
+
+- **Parameters:**
+  - `date: string | Date` — A `Date` or a `YYYY-MM-DD` string.
+- **Returns:** This builder.
+
+<a id="invoice-builder-due-date"></a>
+### `dueDate(date)`
+
+Payment due date.
+
+- **Parameters:**
+  - `date: string | Date` — A `Date` or a `YYYY-MM-DD` string.
+- **Returns:** This builder.
+
+<a id="invoice-builder-main-tax"></a>
+### `mainTax(tax)`
+
+Main tax applied to every line added with `addLine` after this call, unless the
+line passes its own.
+
+- **Parameters:**
+  - `tax: LineMainTax` — For example `{ type: 'IVA', percentage: 21, regime_key: '01' }`.
+- **Returns:** This builder.
+
+<a id="invoice-builder-add-line"></a>
+### `addLine(description, quantity, unitPrice, discountPercentage?, mainTax?)`
+
+Add a `NORMAL` line.
+
+- **Parameters:**
+  - `description: string` — What is invoiced.
+  - `quantity: number` — Units.
+  - `unitPrice: number` — Price per unit before taxes.
+  - `discountPercentage?: number` — Discount, 0–100. Default: `0`. Default: `NO_DISCOUNT`.
+  - `mainTax?: LineMainTax` — Tax of this line; defaults to the one set with `mainTax`. The API rejects a `NORMAL` line without one.
+- **Returns:** This builder.
+
+<a id="invoice-builder-add-line-object"></a>
+### `addLineObject(line)`
+
+Add a line exactly as given — any line type or pricing mode.
+
+- **Parameters:**
+  - `line: InvoiceLine` — A line of `CreateInvoiceRequest`.
+- **Returns:** This builder.
+
+<a id="invoice-builder-notes"></a>
+### `notes(notes)`
+
+Notes printed on the invoice.
+
+- **Parameters:**
+  - `notes: string` — Free text.
+- **Returns:** This builder.
+
+<a id="invoice-builder-series"></a>
+### `series(id)`
+
+Number the invoice in this series instead of the default one.
+
+- **Parameters:**
+  - `id: string` — Series UUID.
+- **Returns:** This builder.
+
+<a id="invoice-builder-metadata"></a>
+### `metadata(data)`
+
+Your own key/value pairs, filterable when listing.
+
+- **Parameters:**
+  - `data: Record<string, any>` — Metadata to store with the invoice.
+- **Returns:** This builder.
+
+<a id="invoice-builder-build"></a>
+### `build()`
+
+Build the request body.
+
+- **Returns:** The `CreateInvoiceRequest`.
+- **Throws:** `Error` When there is no customer or no line.

package/docs/reference/invoices.md

@@ -0,0 +1,250 @@
+<!-- Generated by `npm run docs:reference` from the SDK source and openapi/public-api.yaml. Do not edit. -->
+
+# `beel.invoices` — `InvoicesResource`
+
+[Reference index](README.md)
+
+> **Deprecated.** The contract deprecates the session-focus routes. Use `beel.company(companyId).invoices` instead.
+
+Invoices of the focused company, on the flat `/v1/invoices` routes.
+
+## Methods
+
+| Method | HTTP | Summary |
+|---|---|---|
+| [`beel.invoices.list(params?)`](#invoices-list) | `GET /v1/invoices` | List invoices with optional filters and pagination. |
+| [`beel.invoices.create(body)`](#invoices-create) | `POST /v1/invoices` | Create a new invoice. |
+| [`beel.invoices.get(id)`](#invoices-get) | `GET /v1/invoices/{invoice_id}` | Get an invoice by ID. |
+| [`beel.invoices.update(id, body)`](#invoices-update) | `PUT /v1/invoices/{invoice_id}` | Update a draft invoice. |
+| [`beel.invoices.delete(id)`](#invoices-delete) | `DELETE /v1/invoices/{invoice_id}` | Delete a draft invoice. |
+| [`beel.invoices.duplicate(id, options?)`](#invoices-duplicate) | `POST /v1/invoices/{invoice_id}/duplicate` | Duplicate an invoice, optionally into a different series. |
+| [`beel.invoices.issue(id, options?)`](#invoices-issue) | `POST /v1/invoices/{invoice_id}/issue` | Issue a draft invoice. |
+| [`beel.invoices.markPaid(id, options?)`](#invoices-mark-paid) | `POST /v1/invoices/{invoice_id}/mark-paid` | Mark an invoice as paid. |
+| [`beel.invoices.markSent(id, options?)`](#invoices-mark-sent) | `POST /v1/invoices/{invoice_id}/mark-sent` | Mark an invoice as sent (e.g. delivered by other means). |
+| [`beel.invoices.revertToIssued(id)`](#invoices-revert-to-issued) | `POST /v1/invoices/{invoice_id}/revert-to-issued` | Revert a paid/sent invoice back to issued status. |
+| [`beel.invoices.void(id, params)`](#invoices-void) | `POST /v1/invoices/{invoice_id}/void` | Void an issued invoice. |
+| [`beel.invoices.createCorrective(id, body)`](#invoices-create-corrective) | `POST /v1/invoices/{invoice_id}/corrective` | Create a corrective invoice that references the original. |
+| [`beel.invoices.schedule(id, params)`](#invoices-schedule) | `POST /v1/invoices/{invoice_id}/schedule` | Schedule a draft invoice to be issued on a future date. |
+| [`beel.invoices.unschedule(id)`](#invoices-unschedule) | `POST /v1/invoices/{invoice_id}/unschedule` | Cancel a scheduled invoice, returning it to draft. |
+| [`beel.invoices.reschedule(id, params)`](#invoices-reschedule) | `PATCH /v1/invoices/{invoice_id}/reschedule` | Change the scheduled date of a scheduled invoice. |
+| [`beel.invoices.getPdf(id)`](#invoices-get-pdf) | `GET /v1/invoices/{invoice_id}/pdf` | Get a pre-signed URL to download the invoice PDF. |
+| [`beel.invoices.sendEmail(id, options?)`](#invoices-send-email) | `POST /v1/invoices/{invoice_id}/send` | Send an invoice by email. |
+
+<a id="invoices-list"></a>
+### `list(params?)`
+
+List invoices with optional filters and pagination.
+
+- **HTTP:** `GET /v1/invoices` · operation `listInvoices` · scopes `invoices:read` · **deprecated in the contract**
+- **Parameters:**
+  - `params?: ListParams` — Filters and pagination.
+- **Returns:** The page of `invoices` and its `pagination`. Response `200` `data`: `{ invoices: Invoice[]; pagination: Pagination }`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+**Example**
+
+```typescript
+const { invoices, pagination } = await beel.invoices.list({ status: 'ISSUED', limit: 20 });
+```
+
+<a id="invoices-create"></a>
+### `create(body)`
+
+Create a new invoice. An idempotency key is automatically added.
+
+- **HTTP:** `POST /v1/invoices` · operation `createInvoice` · scopes `invoices:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `body: components['schemas']['CreateInvoiceRequest']` — Type, recipient and lines.
+- **Returns:** The created invoice. Response `201` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+**Example**
+
+```typescript
+const invoice = await beel.invoices.create({
+  type: 'STANDARD',
+  recipient: { customer_id: 'uuid' },
+  lines: [{ description: 'Service', quantity: 1, unit_price: 100, discount_percentage: 0 }],
+});
+```
+
+<a id="invoices-get"></a>
+### `get(id)`
+
+Get an invoice by ID.
+
+- **HTTP:** `GET /v1/invoices/{invoice_id}` · operation `getInvoice` · scopes `invoices:read` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+- **Returns:** The invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-update"></a>
+### `update(id, body)`
+
+Update a draft invoice. Only draft invoices can be updated.
+
+- **HTTP:** `PUT /v1/invoices/{invoice_id}` · operation `updateInvoice` · scopes `invoices:write` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+  - `body: components['schemas']['UpdateInvoiceRequest']` — The draft's new content.
+- **Returns:** The updated invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-delete"></a>
+### `delete(id)`
+
+Delete a draft invoice. Only draft invoices can be deleted.
+
+- **HTTP:** `DELETE /v1/invoices/{invoice_id}` · operation `deleteInvoice` · scopes `invoices:write` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-duplicate"></a>
+### `duplicate(id, options?)`
+
+Duplicate an invoice, optionally into a different series.
+
+- **HTTP:** `POST /v1/invoices/{invoice_id}/duplicate` · operation `duplicateInvoice` · scopes `invoices:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+  - `options?: { series_id?: string; notes?: string }` — `series_id` and `notes` of the copy.
+- **Returns:** The new draft. Response `201` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-issue"></a>
+### `issue(id, options?)`
+
+Issue a draft invoice. Assigns an invoice number and triggers VeriFactu submission.
+
+- **HTTP:** `POST /v1/invoices/{invoice_id}/issue` · operation `issueInvoice` · scopes `invoices:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+  - `options?: { wait_for_pdf?: boolean }` — `wait_for_pdf: true` to wait for the PDF.
+- **Returns:** The issued invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-mark-paid"></a>
+### `markPaid(id, options?)`
+
+Mark an invoice as paid.
+
+- **HTTP:** `POST /v1/invoices/{invoice_id}/mark-paid` · operation `markInvoicePaid` · scopes `invoices:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+  - `options?: { payment_date?: string; payment_method?: any }` — `payment_date` (default: today) and `payment_method`.
+- **Returns:** The paid invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-mark-sent"></a>
+### `markSent(id, options?)`
+
+Mark an invoice as sent (e.g. delivered by other means).
+
+- **HTTP:** `POST /v1/invoices/{invoice_id}/mark-sent` · operation `markInvoiceSent` · scopes `invoices:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+  - `options?: { sent_at?: string }` — `sent_at`.
+- **Returns:** The sent invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-revert-to-issued"></a>
+### `revertToIssued(id)`
+
+Revert a paid/sent invoice back to issued status.
+
+- **HTTP:** `POST /v1/invoices/{invoice_id}/revert-to-issued` · operation `revertInvoiceToIssued` · scopes `invoices:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+- **Returns:** The invoice, back in `ISSUED`. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-void"></a>
+### `void(id, params)`
+
+Void an issued invoice. Requires a reason (min 10 chars).
+
+- **HTTP:** `POST /v1/invoices/{invoice_id}/void` · operation `voidInvoice` · scopes `invoices:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+  - `params: { reason: string; void_date?: string }` — `reason` (min 10 characters) and optional `void_date`.
+- **Returns:** The voided invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+**Example**
+
+```typescript
+await beel.invoices.void('id', { reason: 'Duplicate invoice sent in error' });
+```
+
+<a id="invoices-create-corrective"></a>
+### `createCorrective(id, body)`
+
+Create a corrective invoice that references the original.
+
+- **HTTP:** `POST /v1/invoices/{invoice_id}/corrective` · operation `createCorrectiveInvoice` · scopes `invoices:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — UUID of the issued invoice to correct.
+  - `body: components['schemas']['CreateCorrectiveInvoiceRequest']` — Rectification type, code, reason and lines.
+- **Returns:** The corrective invoice. Response `201` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-schedule"></a>
+### `schedule(id, params)`
+
+Schedule a draft invoice to be issued on a future date.
+
+- **HTTP:** `POST /v1/invoices/{invoice_id}/schedule` · operation `scheduleInvoice` · scopes `invoices:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — UUID of the draft.
+  - `params: { scheduled_for: string; action?: string }` — `scheduled_for` and optional `action`.
+- **Returns:** The scheduled invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-unschedule"></a>
+### `unschedule(id)`
+
+Cancel a scheduled invoice, returning it to draft.
+
+- **HTTP:** `POST /v1/invoices/{invoice_id}/unschedule` · operation `unscheduleInvoice` · scopes `invoices:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+- **Returns:** The invoice, back in draft. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-reschedule"></a>
+### `reschedule(id, params)`
+
+Change the scheduled date of a scheduled invoice.
+
+- **HTTP:** `PATCH /v1/invoices/{invoice_id}/reschedule` · operation `rescheduleInvoice` · scopes `invoices:write` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+  - `params: { scheduled_for: string }` — New `scheduled_for`.
+- **Returns:** The rescheduled invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-get-pdf"></a>
+### `getPdf(id)`
+
+Get a pre-signed URL to download the invoice PDF.
+The URL expires in 5 minutes. Use `beel.downloadPdf(id)` for a simpler Buffer download.
+
+- **HTTP:** `GET /v1/invoices/{invoice_id}/pdf` · operation `generateInvoicePdf` · scopes `invoices:read` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+- **Returns:** `download_url`, `expires_in_seconds` and `file_name`. Response `200` `data`: `{ download_url: string; expires_in_seconds: number; file_name: string }`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="invoices-send-email"></a>
+### `sendEmail(id, options?)`
+
+Send an invoice by email. Uses the customer's email by default.
+
+- **HTTP:** `POST /v1/invoices/{invoice_id}/send` · operation `sendInvoiceEmail` · scopes `invoices:write` · accepts `Idempotency-Key` · **deprecated in the contract**
+- **Parameters:**
+  - `id: string` — Invoice UUID.
+  - `options?: { to?: string[]; cc?: string[]; subject?: string; message?: string }` — Recipients, subject and message.
+- **Returns:** The delivery record. Response `200` `data`: `{ email_id?: UUID; sent_to?: Email[]; sent_at?: string }`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`

package/docs/reference/nif.md

@@ -0,0 +1,31 @@
+<!-- Generated by `npm run docs:reference` from the SDK source and openapi/public-api.yaml. Do not edit. -->
+
+# `beel.nif` — `NifResource`
+
+[Reference index](README.md)
+
+NIF validation against the AEAT register. Reach it as `beel.nif`.
+
+## Methods
+
+| Method | HTTP | Summary |
+|---|---|---|
+| [`beel.nif.validate(nif)`](#nif-validate) | `POST /v1/nif/validate` | Validate a Spanish NIF/CIF against the AEAT tax registry. |
+
+<a id="nif-validate"></a>
+### `validate(nif)`
+
+Validate a Spanish NIF/CIF against the AEAT tax registry.
+
+- **HTTP:** `POST /v1/nif/validate` · operation `validateNif` · scopes `nif:validate`
+- **Parameters:**
+  - `nif: string` — The NIF/CIF to validate.
+- **Returns:** Whether it is valid and, when the register knows it, its holder's name. Response `200` `data`: `ValidateNifResponse`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+**Example**
+
+```typescript
+const result = await beel.nif.validate('B12345678');
+console.log(result.valid, result.name);
+```