@beel_es/sdk 1.3.0 → 2.1.0

package/docs/reference/company-invoices.md

@@ -0,0 +1,316 @@
+<!-- Generated by `npm run docs:reference` from the SDK source and openapi/public-api.yaml. Do not edit. -->
+
+# `beel.company(companyId).invoices` — `CompanyInvoicesResource`
+
+[Reference index](README.md)
+
+Invoice lifecycle of one company: create a draft (or issue it directly), issue, void,
+correct, list and read, PDF and email. Reach it as `beel.company(companyId).invoices`.
+
+A create, issue, void or corrective carries an automatic `Idempotency-Key`, reused by the
+client's automatic retries. To retry a create yourself safely, use `createOnce`.
+
+## Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `schedule` | [`CompanyInvoiceScheduleResource`](company-invoices-schedule.md) | Scheduled issuing of one invoice: read, set or clear it. |
+
+## Methods
+
+| Method | HTTP | Summary |
+|---|---|---|
+| [`beel.company(companyId).invoices.derive(body, options?)`](#company-invoices-derive) | `POST /v1/companies/{company_id}/invoices/derivations` | Derive a new draft invoice from an existing one — the canonical form of `duplicate`. |
+| [`beel.company(companyId).invoices.list(params?, options?)`](#company-invoices-list) | `GET /v1/companies/{company_id}/invoices` | List the company's invoices, paginated, with filters: status, type, customer, dates, `external_ref` (exact match), VeriFactu status and more. |
+| [`beel.company(companyId).invoices.create(body, params?, options?)`](#company-invoices-create) | `POST /v1/companies/{company_id}/invoices` | Create an invoice: a `DRAFT` by default, or numbered and issued in the same call with `options.issue_directly: true`. |
+| [`beel.company(companyId).invoices.createOnce(body, params?, options?)`](#company-invoices-create-once) | via `list`, `create` | Create a standard or simplified invoice once per `external_ref`, safe to call again after any failure. |
+| [`beel.company(companyId).invoices.get(invoiceId, options?)`](#company-invoices-get) | `GET /v1/companies/{company_id}/invoices/{invoice_id}` | Get one invoice, including its `status` and its `verifactu` block (`submission_status`, `qr_url`, `error_code`…). |
+| [`beel.company(companyId).invoices.update(invoiceId, body, options?)`](#company-invoices-update) | `PATCH /v1/companies/{company_id}/invoices/{invoice_id}` | Update a `DRAFT` or `SCHEDULED` invoice (or an `ACTIVE` proforma). |
+| [`beel.company(companyId).invoices.delete(invoiceId, options?)`](#company-invoices-delete) | `DELETE /v1/companies/{company_id}/invoices/{invoice_id}` | Delete a draft invoice. |
+| [`beel.company(companyId).invoices.issue(invoiceId, params?, options?)`](#company-invoices-issue) | `POST /v1/companies/{company_id}/invoices/{invoice_id}/issue` | Issue a draft: assigns its definitive number and makes it immutable. |
+| [`beel.company(companyId).invoices.void(invoiceId, body, options?)`](#company-invoices-void) | `POST /v1/companies/{company_id}/invoices/{invoice_id}/void` | Void an invoice issued by mistake. |
+| [`beel.company(companyId).invoices.createCorrective(invoiceId, body, options?)`](#company-invoices-create-corrective) | `POST /v1/companies/{company_id}/invoices/{invoice_id}/corrective` | Create a corrective invoice (rectificativa) for an issued invoice. |
+| [`beel.company(companyId).invoices.convertToInvoice(invoiceId, body?, options?)`](#company-invoices-convert-to-invoice) | `POST /v1/companies/{company_id}/invoices/{invoice_id}/convert-to-invoice` | Convert a proforma into an invoice. |
+| [`beel.company(companyId).invoices.createSimplifiedExchange(body, options?)`](#company-invoices-create-simplified-exchange) | `POST /v1/companies/{company_id}/invoices/simplified-exchanges` | Issue a full invoice in exchange for one or more issued simplified invoices, when the customer asks for an invoice with their details. |
+| [`beel.company(companyId).invoices.verifactuRecords(invoiceId, options?)`](#company-invoices-verifactu-records) | `GET /v1/companies/{company_id}/invoices/{invoice_id}/verifactu-records` | The VeriFactu records of an invoice, oldest first: its registration and, if it was voided, its cancellation. |
+| [`beel.company(companyId).invoices.setStatus(invoiceId, body, options?)`](#company-invoices-set-status) | `PUT /v1/companies/{company_id}/invoices/{invoice_id}/status` | Set the commercial status: `PAID` (from `ISSUED`, `SENT`, `OVERDUE`), `SENT` (from `ISSUED`) or back to `ISSUED` (from `SENT`). |
+| [`beel.company(companyId).invoices.getPdf(invoiceId, options?)`](#company-invoices-get-pdf) | `GET /v1/companies/{company_id}/invoices/{invoice_id}/pdf` | Get a short-lived download URL for the invoice PDF. |
+| [`beel.company(companyId).invoices.send(invoiceId, body, options?)`](#company-invoices-send) | `POST /v1/companies/{company_id}/invoices/{invoice_id}/send` | Send the invoice by email with its PDF. |
+
+<a id="company-invoices-derive"></a>
+### `derive(body, options?)`
+
+Derive a new draft invoice from an existing one — the canonical form of `duplicate`.
+The source invoice is not modified.
+
+- **HTTP:** `POST /v1/companies/{company_id}/invoices/derivations` · operation `createCompanyInvoiceDerivation` · scopes `invoices:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `body: components['schemas']['CreateInvoiceDerivationRequest']` — `from_invoice_id`, and optionally the `series_id` of the copy.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The new draft invoice. Response `201` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-invoices-list"></a>
+### `list(params?, options?)`
+
+List the company's invoices, paginated, with filters: status, type, customer, dates,
+`external_ref` (exact match), VeriFactu status and more.
+
+- **HTTP:** `GET /v1/companies/{company_id}/invoices` · operation `listCompanyInvoices` · scopes `invoices:read`
+- **Parameters:**
+  - `params?: operations['listCompanyInvoices']['parameters']['query']` — Filters and pagination (`page`, `limit`).
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **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 } = await company.invoices.list({ external_ref: 'ORD-2026-0042' });
+```
+
+<a id="company-invoices-create"></a>
+### `create(body, params?, options?)`
+
+Create an invoice: a `DRAFT` by default, or numbered and issued in the same call with
+`options.issue_directly: true`. `CORRECTIVE` is not accepted here: use
+`createCorrective`.
+
+One call sends one `Idempotency-Key`, reused by the client's automatic retries, so
+those never duplicate the invoice. A second call is a new operation: to repeat a create
+whose outcome you do not know, use `createOnce`.
+
+- **HTTP:** `POST /v1/companies/{company_id}/invoices` · operation `createCompanyInvoice` · scopes `invoices:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `body: components['schemas']['CreateInvoiceRequest']` — Type, recipient and lines; `external_ref` to tie it to your order.
+  - `params?: operations['createCompanyInvoice']['parameters']['query']` — `wait_for_pdf`, when issuing directly.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The created invoice. With VeriFactu, `verifactu.submission_status` starts `PENDING`. Response `201` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+**Example**
+
+```typescript
+const invoice = await company.invoices.create({
+  type: 'STANDARD',
+  recipient: { customer_id: 'customer-uuid' },
+  lines: [{
+    description: 'Consulting', quantity: 1, unit_price: 100,
+    main_tax: { type: 'IVA', percentage: 21, regime_key: '01' },
+  }],
+  external_ref: 'ORD-2026-0042',
+});
+```
+
+<a id="company-invoices-create-once"></a>
+### `createOnce(body, params?, options?)`
+
+Create a standard or simplified invoice once per `external_ref`, safe to call again
+after any failure. It looks the reference up first and returns the invoice that already
+holds it; otherwise it creates one. If the create answers
+`409 INVOICE_DUPLICATE_EXTERNAL_REFERENCE`, or its outcome is unknown (network error,
+`5xx`), it looks the reference up again and returns the invoice it finds.
+
+The returned invoice may be one created earlier, in any status (`VOIDED` included):
+compare its fields if that matters to you.
+
+- **HTTP:** through [`list`](#company-invoices-list), [`create`](#company-invoices-create)
+- **Parameters:**
+  - `body: CreateInvoiceOnceRequest` — A `CreateInvoiceRequest` with `type` `STANDARD` or `SIMPLIFIED` and a non-empty `external_ref`. See [`CreateInvoiceOnceRequest`](types.md#createinvoiceoncerequest).
+  - `params?: CreateInvoiceOnceParams` — `wait_for_pdf`, when issuing directly. See [`CreateInvoiceOnceParams`](types.md#createinvoiceonceparams).
+  - `options?: RequestOptions` — `idempotencyKey` for the create; `signal` and `timeoutMs` for the whole sequence of calls. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The one invoice that holds `body.external_ref`.
+- **Throws:** `TypeError` Before any request, when `external_ref` is empty or `type` is not `STANDARD`/`SIMPLIFIED`.<br>`BeeLApiError` The create's error when no invoice holds the reference afterwards — nothing was created, so calling again is safe.
+
+**Example**
+
+```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 },
+});
+```
+
+<a id="company-invoices-get"></a>
+### `get(invoiceId, options?)`
+
+Get one invoice, including its `status` and its `verifactu` block
+(`submission_status`, `qr_url`, `error_code`…).
+
+- **HTTP:** `GET /v1/companies/{company_id}/invoices/{invoice_id}` · operation `getCompanyInvoice` · scopes `invoices:read`
+- **Parameters:**
+  - `invoiceId: string` — Invoice UUID.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="company-invoices-update"></a>
+### `update(invoiceId, body, options?)`
+
+Update a `DRAFT` or `SCHEDULED` invoice (or an `ACTIVE` proforma). Only the fields
+present in `body` change; an issued invoice is amended with a corrective instead.
+
+- **HTTP:** `PATCH /v1/companies/{company_id}/invoices/{invoice_id}` · operation `patchCompanyInvoice` · scopes `invoices:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `invoiceId: string` — Invoice UUID.
+  - `body: operations['patchCompanyInvoice']['requestBody']['content']['application/json']` — Fields to change.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The updated invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-invoices-delete"></a>
+### `delete(invoiceId, options?)`
+
+Delete a draft invoice. Deleting frees its `external_ref` for a new invoice.
+
+- **HTTP:** `DELETE /v1/companies/{company_id}/invoices/{invoice_id}` · operation `deleteCompanyInvoice` · scopes `invoices:write`
+- **Parameters:**
+  - `invoiceId: string` — Invoice UUID.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="company-invoices-issue"></a>
+### `issue(invoiceId, params?, options?)`
+
+Issue a draft: assigns its definitive number and makes it immutable. PDF generation and
+the VeriFactu submission happen after the response.
+
+- **HTTP:** `POST /v1/companies/{company_id}/invoices/{invoice_id}/issue` · operation `issueCompanyInvoice` · scopes `invoices:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `invoiceId: string` — UUID of the draft.
+  - `params?: operations['issueCompanyInvoice']['parameters']['query']` — `wait_for_pdf: true` to wait for the PDF before answering.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **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="company-invoices-void"></a>
+### `void(invoiceId, body, options?)`
+
+Void an invoice issued by mistake. The document is kept and its number never reused. If
+the operation did happen but the invoice is wrong, use `createCorrective`.
+
+- **HTTP:** `POST /v1/companies/{company_id}/invoices/{invoice_id}/void` · operation `voidCompanyInvoice` · scopes `invoices:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `invoiceId: string` — Invoice UUID.
+  - `body: NonNullable<operations['voidCompanyInvoice']['requestBody']>['content']['application/json']` — `reason`; `issued_in_error: true` is required once it was sent or paid.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The voided invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-invoices-create-corrective"></a>
+### `createCorrective(invoiceId, body, options?)`
+
+Create a corrective invoice (rectificativa) for an issued invoice.
+
+- **HTTP:** `POST /v1/companies/{company_id}/invoices/{invoice_id}/corrective` · operation `createCompanyCorrectiveInvoice` · scopes `invoices:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `invoiceId: string` — UUID of the issued invoice to correct.
+  - `body: operations['createCompanyCorrectiveInvoice']['requestBody']['content']['application/json']` — `rectification_type` (`TOTAL`/`PARTIAL`), `rectification_code` (`R1`–`R5`), `reason` and, for `PARTIAL`, the correcting `lines`.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The corrective invoice. Response `201` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+**Example**
+
+```typescript
+const corrective = await company.invoices.createCorrective('invoice-uuid', {
+  rectification_type: 'PARTIAL',
+  rectification_code: 'R1',
+  reason: 'Discount agreed with the customer after the sale',
+  lines: [{ description: 'Discount', quantity: -1, unit_price: 10,
+    main_tax: { type: 'IVA', percentage: 21, regime_key: '01' } }],
+});
+```
+
+<a id="company-invoices-convert-to-invoice"></a>
+### `convertToInvoice(invoiceId, body?, options?)`
+
+Convert a proforma into an invoice.
+
+- **HTTP:** `POST /v1/companies/{company_id}/invoices/{invoice_id}/convert-to-invoice` · operation `convertCompanyProformaToInvoice` · scopes `invoices:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `invoiceId: string` — UUID of the proforma.
+  - `body?: NonNullable<operations['convertCompanyProformaToInvoice']['requestBody']>['content']['application/json']` — Optional overrides for the new invoice.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The new invoice. Response `201` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-invoices-create-simplified-exchange"></a>
+### `createSimplifiedExchange(body, options?)`
+
+Issue a full invoice in exchange for one or more issued simplified invoices, when the
+customer asks for an invoice with their details. It is not a corrective: the simplified
+invoices become `VOIDED` with `void_cause: 'EXCHANGED'`, and the new `STANDARD` invoice
+lists them in `replaced_invoice_ids`.
+
+- **HTTP:** `POST /v1/companies/{company_id}/invoices/simplified-exchanges` · operation `createCompanySimplifiedExchange` · scopes `invoices:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `body: components['schemas']['CreateSimplifiedExchangeRequest']` — `simplified_invoice_ids` and the identified `recipient`.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The new standard invoice. Response `201` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+**Example**
+
+```typescript
+const invoice = await company.invoices.createSimplifiedExchange({
+  simplified_invoice_ids: ['simplified-uuid'],
+  recipient: { customer_id: 'customer-uuid' },
+});
+```
+
+<a id="company-invoices-verifactu-records"></a>
+### `verifactuRecords(invoiceId, options?)`
+
+The VeriFactu records of an invoice, oldest first: its registration and, if it was
+voided, its cancellation. An invoice never submitted answers with an empty list.
+
+- **HTTP:** `GET /v1/companies/{company_id}/invoices/{invoice_id}/verifactu-records` · operation `listCompanyInvoiceVerifactuRecords` · scopes `invoices:read`
+- **Parameters:**
+  - `invoiceId: string` — Invoice UUID.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The records (`data.records` of the response), each with its own `submission_status`. Response `200` `data`: `{ records: VeriFactuRecord[] }`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="company-invoices-set-status"></a>
+### `setStatus(invoiceId, body, options?)`
+
+Set the commercial status: `PAID` (from `ISSUED`, `SENT`, `OVERDUE`), `SENT` (from
+`ISSUED`) or back to `ISSUED` (from `SENT`). Issuing and voiding have their own methods.
+
+- **HTTP:** `PUT /v1/companies/{company_id}/invoices/{invoice_id}/status` · operation `setCompanyInvoiceStatus` · scopes `invoices:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `invoiceId: string` — Invoice UUID.
+  - `body: operations['setCompanyInvoiceStatus']['requestBody']['content']['application/json']` — Target `status` and, for `PAID`, the payment details.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **Returns:** The updated invoice. Response `200` `data`: `Invoice`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-invoices-get-pdf"></a>
+### `getPdf(invoiceId, options?)`
+
+Get a short-lived download URL for the invoice PDF.
+
+- **HTTP:** `GET /v1/companies/{company_id}/invoices/{invoice_id}/pdf` · operation `getCompanyInvoicePdf` · scopes `invoices:read`
+- **Parameters:**
+  - `invoiceId: string` — Invoice UUID.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **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="company-invoices-send"></a>
+### `send(invoiceId, body, options?)`
+
+Send the invoice by email with its PDF. Without recipients, the customer's addresses are used.
+
+- **HTTP:** `POST /v1/companies/{company_id}/invoices/{invoice_id}/send` · operation `sendCompanyInvoice` · scopes `invoices:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `invoiceId: string` — Invoice UUID.
+  - `body: NonNullable<operations['sendCompanyInvoice']['requestBody']>['content']['application/json']` — Optional recipients, subject and message.
+  - `options?: RequestOptions` — Per-call `idempotencyKey`, `signal` and `timeoutMs`. See [`RequestOptions`](types.md#requestoptions).
+- **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/company-payment-connections-events.md

@@ -0,0 +1,103 @@
+<!-- Generated by `npm run docs:reference` from the SDK source and openapi/public-api.yaml. Do not edit. -->
+
+# `beel.company(companyId).paymentConnections.events(connectionId)` — `CompanyPaymentEventsResource`
+
+[Reference index](README.md)
+
+Payment events received through a connection, and the recovery levers for the ones
+that did not produce an invoice. Reach it as
+`beel.company(companyId).paymentConnections.events(connectionId)`.
+
+## Methods
+
+| Method | HTTP | Summary |
+|---|---|---|
+| [`beel.company(companyId).paymentConnections.events(connectionId).list(params?)`](#company-payment-connections-events-list) | `GET /v1/companies/{company_id}/payment-connections/{connection_id}/events` | Events of the connection, most recent first. |
+| [`beel.company(companyId).paymentConnections.events(connectionId).get(eventId)`](#company-payment-connections-events-get) | `GET /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}` | Get one event. |
+| [`beel.company(companyId).paymentConnections.events(connectionId).retry(eventId)`](#company-payment-connections-events-retry) | `POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/retry` | Reprocess an event whose automatic invoicing didn't complete, applying the NIF's **current** configuration. |
+| [`beel.company(companyId).paymentConnections.events(connectionId).draft(eventId)`](#company-payment-connections-events-draft) | `POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/draft` | Build a **draft** invoice from an event that couldn't be invoiced automatically, so you can review it before issuing. |
+| [`beel.company(companyId).paymentConnections.events(connectionId).resolve(eventId)`](#company-payment-connections-events-resolve) | `POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/resolve` | Mark an event as dealt with outside the automatic flow. |
+| [`beel.company(companyId).paymentConnections.events(connectionId).discard(eventId)`](#company-payment-connections-events-discard) | `POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/discard` | Discard an event so it stops asking for attention. |
+| [`beel.company(companyId).paymentConnections.events(connectionId).restore(eventId)`](#company-payment-connections-events-restore) | `POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/restore` | Bring a discarded event back into the list. |
+
+<a id="company-payment-connections-events-list"></a>
+### `list(params?)`
+
+Events of the connection, most recent first. Nothing is hidden by default:
+skipped events, duplicates and disputes are all returned — narrow with the
+filters. `charges_only` returns one row per money movement instead.
+
+- **HTTP:** `GET /v1/companies/{company_id}/payment-connections/{connection_id}/events` · operation `listCompanyPaymentEvents` · scopes `payment-connections:read`
+- **Parameters:**
+  - `params?: operations['listCompanyPaymentEvents']['parameters']['query']` — Filters (`needs_action`, `charges_only`…) and pagination.
+- **Returns:** The `events`, their `pagination` and `counts`. Response `200` `data`: `{ events: ManagedPaymentEvent[]; pagination?: Pagination; counts?: PaymentEventCounts }`.
+- **Throws:** `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError` · `500` `BeeLApiError`
+
+<a id="company-payment-connections-events-get"></a>
+### `get(eventId)`
+
+Get one event.
+
+- **HTTP:** `GET /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}` · operation `getCompanyPaymentEvent` · scopes `payment-connections:read`
+- **Parameters:**
+  - `eventId: string` — Event UUID.
+- **Returns:** The event. Response `200` `data`: `ManagedPaymentEvent`.
+- **Throws:** `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError` · `500` `BeeLApiError`
+
+<a id="company-payment-connections-events-retry"></a>
+### `retry(eventId)`
+
+Reprocess an event whose automatic invoicing didn't complete, applying the NIF's
+**current** configuration. Only retryable states qualify and the retry budget is
+finite: otherwise `400`.
+
+- **HTTP:** `POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/retry` · operation `retryCompanyPaymentEvent` · scopes `payment-connections:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `eventId: string` — Event UUID.
+- **Returns:** The event after the retry. Response `200` `data`: `ManagedPaymentEvent`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-payment-connections-events-draft"></a>
+### `draft(eventId)`
+
+Build a **draft** invoice from an event that couldn't be invoiced automatically,
+so you can review it before issuing.
+
+- **HTTP:** `POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/draft` · operation `generateCompanyPaymentEventDraft` · scopes `payment-connections:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `eventId: string` — Event UUID.
+- **Returns:** The draft's `invoice_id`. Response `201` `data`: `{ invoice_id: string }`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-payment-connections-events-resolve"></a>
+### `resolve(eventId)`
+
+Mark an event as dealt with outside the automatic flow.
+
+- **HTTP:** `POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/resolve` · operation `resolveCompanyPaymentEvent` · scopes `payment-connections:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `eventId: string` — Event UUID.
+- **Returns:** The resolved event. Response `200` `data`: `ManagedPaymentEvent`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-payment-connections-events-discard"></a>
+### `discard(eventId)`
+
+Discard an event so it stops asking for attention. Reversible with `restore`.
+
+- **HTTP:** `POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/discard` · operation `discardCompanyPaymentEvent` · scopes `payment-connections:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `eventId: string` — Event UUID.
+- **Returns:** The discarded event. Response `200` `data`: `ManagedPaymentEvent`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-payment-connections-events-restore"></a>
+### `restore(eventId)`
+
+Bring a discarded event back into the list.
+
+- **HTTP:** `POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/restore` · operation `restoreCompanyPaymentEvent` · scopes `payment-connections:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `eventId: string` — Event UUID.
+- **Returns:** The restored event. Response `200` `data`: `ManagedPaymentEvent`.
+- **Throws:** `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError` · `500` `BeeLApiError`

package/docs/reference/company-payment-connections.md

@@ -0,0 +1,87 @@
+<!-- Generated by `npm run docs:reference` from the SDK source and openapi/public-api.yaml. Do not edit. -->
+
+# `beel.company(companyId).paymentConnections` — `CompanyPaymentConnectionsResource`
+
+[Reference index](README.md)
+
+Payment connections of a company (NIF): the Stripe Connect link whose charges
+auto-generate invoices under that NIF.
+
+A connection is addressed by **its own UUID**, not by the provider slug — a NIF can
+hold several connections of the same provider, so the slug does not name one. Take
+`id` from `list`. The slug only appears when you *start* an authorization.
+
+**Example**
+
+```typescript
+const company = beel.company('company-uuid');
+const { connections } = await company.paymentConnections.list();
+const events = await company.paymentConnections.events(connections[0].id).list({
+  needs_action: true,
+});
+```
+
+## Methods
+
+| Method | HTTP | Summary |
+|---|---|---|
+| [`beel.company(companyId).paymentConnections.list()`](#company-payment-connections-list) | `GET /v1/companies/{company_id}/payment-connections` | Every payment connection of this company. |
+| [`beel.company(companyId).paymentConnections.authorize(body)`](#company-payment-connections-authorize) | `POST /v1/companies/{company_id}/payment-connections/authorizations` | Start an authorization and get the URL where the NIF's holder approves it. |
+| [`beel.company(companyId).paymentConnections.update(connectionId, body)`](#company-payment-connections-update) | `PATCH /v1/companies/{company_id}/payment-connections/{connection_id}` | Update the settings of one connection, addressed by its UUID. |
+| [`beel.company(companyId).paymentConnections.disconnect(connectionId)`](#company-payment-connections-disconnect) | `DELETE /v1/companies/{company_id}/payment-connections/{connection_id}` | Disconnect one connection. |
+| [`beel.company(companyId).paymentConnections.events(connectionId)`](#company-payment-connections-events) | — | The payment events of one connection — where you audit what did and didn't invoice. |
+
+<a id="company-payment-connections-list"></a>
+### `list()`
+
+Every payment connection of this company.
+
+- **HTTP:** `GET /v1/companies/{company_id}/payment-connections` · operation `listCompanyPaymentConnections` · scopes `payment-connections:read`
+- **Returns:** The `connections`. Response `200` `data`: `{ connections: ManagedPaymentConnection[] }`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `429` `BeeLRateLimitError`
+
+<a id="company-payment-connections-authorize"></a>
+### `authorize(body)`
+
+Start an authorization and get the URL where the NIF's holder approves it.
+
+This is the one place the provider slug is used — currently only `stripe`.
+
+- **HTTP:** `POST /v1/companies/{company_id}/payment-connections/authorizations` · operation `initiatePaymentConnection` · scopes `payment-connections:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `body: components['schemas']['InitiatePaymentConnectionRequest']` — `{ provider: 'stripe' }`, plus the return URL when needed.
+- **Returns:** The `authorization_url` to send the NIF's holder to. Response `200` `data`: `{ authorization_url: string }`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-payment-connections-update"></a>
+### `update(connectionId, body)`
+
+Update the settings of one connection, addressed by its UUID.
+
+- **HTTP:** `PATCH /v1/companies/{company_id}/payment-connections/{connection_id}` · operation `updateCompanyPaymentConnection` · scopes `payment-connections:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `connectionId: string` — Connection UUID, from `list`.
+  - `body: components['schemas']['UpdateCompanyPaymentConnectionRequest']` — Settings to change.
+- **Returns:** The updated connection. Response `200` `data`: `CompanyPaymentConnection`.
+- **Throws:** `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError` · `500` `BeeLApiError`
+
+<a id="company-payment-connections-disconnect"></a>
+### `disconnect(connectionId)`
+
+Disconnect one connection. Tokens are revoked and auto-invoicing stops;
+already-issued invoices are untouched.
+
+- **HTTP:** `DELETE /v1/companies/{company_id}/payment-connections/{connection_id}` · operation `disconnectCompanyPaymentConnection` · scopes `payment-connections:write`
+- **Parameters:**
+  - `connectionId: string` — Connection UUID.
+- **Returns:** `Promise<void>`
+- **Throws:** `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError` · `500` `BeeLApiError`
+
+<a id="company-payment-connections-events"></a>
+### `events(connectionId)`
+
+The payment events of one connection — where you audit what did and didn't invoice.
+
+- **Parameters:**
+  - `connectionId: string` — Connection UUID.
+- **Returns:** The events resource of that connection. No request is made.

package/docs/reference/company-products.md

@@ -0,0 +1,72 @@
+<!-- Generated by `npm run docs:reference` from the SDK source and openapi/public-api.yaml. Do not edit. -->
+
+# `beel.company(companyId).products` — `CompanyProductsResource`
+
+[Reference index](README.md)
+
+Products and services of one company. Reach it as `beel.company(companyId).products`.
+
+## Methods
+
+| Method | HTTP | Summary |
+|---|---|---|
+| [`beel.company(companyId).products.list(params?)`](#company-products-list) | `GET /v1/companies/{company_id}/products` | List the company's products, paginated and searchable. |
+| [`beel.company(companyId).products.create(body)`](#company-products-create) | `POST /v1/companies/{company_id}/products` | Create a product or service. |
+| [`beel.company(companyId).products.get(productId)`](#company-products-get) | `GET /v1/companies/{company_id}/products/{product_id}` | Get one product. |
+| [`beel.company(companyId).products.update(productId, body)`](#company-products-update) | `PATCH /v1/companies/{company_id}/products/{product_id}` | Update a product. |
+| [`beel.company(companyId).products.delete(productId)`](#company-products-delete) | `DELETE /v1/companies/{company_id}/products/{product_id}` | Delete a product from the catalog. |
+
+<a id="company-products-list"></a>
+### `list(params?)`
+
+List the company's products, paginated and searchable.
+
+- **HTTP:** `GET /v1/companies/{company_id}/products` · operation `listCompanyProducts` · scopes `products:read`
+- **Parameters:**
+  - `params?: operations['listCompanyProducts']['parameters']['query']` — Filters and pagination.
+- **Returns:** The page of `products` and its `pagination`. Response `200` `data`: `{ products: Product[]; pagination: Pagination }`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-products-create"></a>
+### `create(body)`
+
+Create a product or service.
+
+- **HTTP:** `POST /v1/companies/{company_id}/products` · operation `createCompanyProduct` · scopes `products:write` · accepts `Idempotency-Key`
+- **Parameters:**
+  - `body: components['schemas']['CreateProductRequest']` — Name, category, price and main tax.
+- **Returns:** The created product. Response `201` `data`: `Product`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-products-get"></a>
+### `get(productId)`
+
+Get one product.
+
+- **HTTP:** `GET /v1/companies/{company_id}/products/{product_id}` · operation `getCompanyProduct` · scopes `products:read`
+- **Parameters:**
+  - `productId: string` — Product UUID.
+- **Returns:** The product. Response `200` `data`: `Product`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError`
+
+<a id="company-products-update"></a>
+### `update(productId, body)`
+
+Update a product. Only the fields present in `body` change.
+
+- **HTTP:** `PATCH /v1/companies/{company_id}/products/{product_id}` · operation `patchCompanyProduct` · scopes `products:write`
+- **Parameters:**
+  - `productId: string` — Product UUID.
+  - `body: operations['patchCompanyProduct']['requestBody']['content']['application/json']` — Fields to change.
+- **Returns:** The updated product. Response `200` `data`: `Product`.
+- **Throws:** `400`/`500` `BeeLApiError` · `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `409` `BeeLConflictError` · `422` `BeeLValidationError` · `429` `BeeLRateLimitError`
+
+<a id="company-products-delete"></a>
+### `delete(productId)`
+
+Delete a product from the catalog. Existing invoice lines are unaffected.
+
+- **HTTP:** `DELETE /v1/companies/{company_id}/products/{product_id}` · operation `deleteCompanyProduct` · scopes `products:write`
+- **Parameters:**
+  - `productId: string` — Product UUID.
+- **Throws:** `401`/`403` `BeeLAuthError` · `404` `BeeLNotFoundError` · `429` `BeeLRateLimitError` · `500` `BeeLApiError`