BeeL

Updates only the fields present in the body, leaving every other field of the recurring invoice template as it is. - **Omitted vs `null`:** an omitted field keeps its current value; a field sent as `null` is cleared, and only where the request schema documents the field as nullable. - **`lines`:** replaced as a whole, not patched line by line. The recipient survives the change, and an empty array is rejected. - **`payment_method`:** replaced as a whole together with `payment_iban`, `payment_swift` and `payment_term_days` — send them in the same request or they are dropped. - **Schedule:** `day_of_month` and `start_date` stay put unless you send them; sending `day_of_month` moves the next generation. `start_date` is only editable while the template has not generated any invoice yet. Endpoint: PATCH /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id} ⚠️ Fiscal guardrails — read before calling: - How BeeL derives the AEAT invoice type, and the rules each type imposes. (resource: beel://guardrails/invoice-types) - What regime_key means, where it lives, and which combinations are rejected. (resource: beel://guardrails/regime-keys) For the exhaustive rules and worked examples, call beel_docs_search.

Updates only the fields present in the body, leaving every other field of the series as it is. - **Clearing a field:** a field sent as `null` is cleared, which only `description` supports. - **Numbering fields:** `code`, `format`, `counter_reset` and `initial_number` are rejected once the series has issued invoices (`numbering_locked` is `true`). - **`default_series`:** it cannot be used to clear the default. Sending `false` for the series that currently is the default answers `DEFAULT_CANNOT_BE_UNMARKED`, because it would leave the document type with active series and no default, and issuing without an explicit `series_id` would then fail with `SERIES_DEFAULT_NOT_FOUND`. Hand the default over with `PUT /v1/companies/{company_id}/series/{series_id}/default` on the new series, which unmarks the previous one. Sending `false` for a series that is not the default is a no-op. Endpoint: PATCH /v1/companies/{company_id}/series/{series_id} ⚠️ Fiscal guardrails — read before calling: - How invoice numbers are formed, and why numbering can never be rewritten. (resource: beel://guardrails/series-and-numbering) For the exhaustive rules and worked examples, call beel_docs_search.

Updates the fields present in the body — `url`, `events`, `active`, `account_relationship` — and leaves the rest untouched. - **`events`:** replaces the whole list, it does not add to it, so an event left out of it stops being delivered. - **`active`:** setting it to `false` stops deliveries without discarding the delivery history. A subscription we turned off ourselves (`deactivated_by: beel`) needs a successful test delivery before it can be turned back on. - **Signing secret:** not touched here. Rotate it with `POST /v1/accounts/{account_id}/webhooks/{webhook_id}/secret`. Endpoint: PATCH /v1/accounts/{account_id}/webhooks/{webhook_id}

Provisions a new account on BeeL and, when it is born with a holder, returns a single-use `claim_token` to deliver so they can set a password and take ownership. - **`email`:** send it to create the account with a holder. Omit it and the account is created with no person at all, no `person_id` and no `claim_token`; a holder can be added later with `POST /v1/accounts/{account_id}/claim-tokens`. - **`tax_profile`:** send it and the account comes back ready to invoice, with its NIF, default invoice series and VeriFactu configuration set up and its `company_id` in the response. Omit it and the account stays empty until its holder registers a NIF. - **`access_level`:** the access you retain over the account. Defaults to `NONE`; `OPERATE` requires a `tax_profile`. - **`external_ref`:** the idempotency key. Resending the same one returns the existing account rather than creating a second. - **Entitlement:** requires `manage_accounts`. ## Reactivation If you previously ended your management of this account (`DELETE /v1/accounts/{account_id}/management`) and its holder has not claimed it yet, provisioning the same email reactivates that account instead of creating a new one. The same account, holder, NIFs and invoices come back under your management, with the `external_ref` and `access_level` of this request, and it counts towards your billable usage again. Once the holder has claimed the account it is theirs, and only they can grant you access again. Endpoint: POST /v1/accounts

Grants a `MEMBER` access to one company, or changes the `access_level` of an existing grant. Only the company in the path is touched. - **Scope:** the member's other grants are left exactly as they were. - **`access_level`:** `VIEW` or `OPERATE`. `NONE` is not accepted here — remove access by deleting the grant. - **Eligible members:** grants apply only to `MEMBER`. `OWNER` and `ADMIN` reach every company implicitly and cannot receive grants. Endpoint: PUT /v1/accounts/{account_id}/members/{member_id}/grants/{company_id}

Reprocesses a payment event whose automatic invoicing did not complete, applying the configuration of the NIF as it stands now. Use it after fixing what caused the failure, for example a missing invoice series. - **`retry_available`:** only events where it is `true` can be retried. Read it instead of deriving retryability from `status` yourself; anything else returns `400`. - **Limit:** the status and the skip reason must admit reprocessing, and the event must still be under the limit of 3 retries (`retry_count`). Endpoint: POST /v1/companies/{company_id}/payment-connections/{provider}/events/{event_id}/retry

Re-sends the original payload of a delivery immediately. - **Payload:** the one captured when the event happened, not a fresh snapshot, so changes made to the entity since then are not reflected. - **History:** the outcome is recorded as a new entry and the original entry is kept as it was. `attempt_number` continues the same sequence, so it can exceed the 5 automatic attempts. Endpoint: POST /v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/retry

Generates a new HMAC signing secret for a webhook subscription. - **Old secret:** **immediately invalidated**. Update your signature verification logic before rotating, to avoid missing events during the transition. - **New secret:** returned **once**, in this response only. It cannot be read again. Endpoint: POST /v1/accounts/{account_id}/webhooks/{webhook_id}/secret

Sends the invoice by email, attaching its PDF by default. When no recipient is given, the addresses configured on the customer are used. Endpoint: POST /v1/companies/{company_id}/invoices/{invoice_id}/send

Marks an invoice series as the default of its document type for this company, and unmarks the previous one. - **One per type:** only one series can be the default per company and document type. - **Must be active:** an inactive series is rejected with `400`. - **Idempotent:** repeating the call changes nothing. Endpoint: PUT /v1/companies/{company_id}/series/{series_id}/default ⚠️ Fiscal guardrails — read before calling: - How invoice numbers are formed, and why numbering can never be rewritten. (resource: beel://guardrails/series-and-numbering) For the exhaustive rules and worked examples, call beel_docs_search.

Replaces the scheduling of a draft invoice, whether it had one or not, moving it to `SCHEDULED`. Both fields of the body are required. - **`scheduled_for`:** the date the invoice is processed on. Today or later; an earlier date is rejected with `422 SCHEDULED_DATE_IN_PAST`. - **`generation_mode`:** `DRAFT` leaves the invoice as a draft for manual review, `ISSUE_AND_SEND` issues and sends it automatically. There is no default. - **Availability:** requires the `scheduled_invoices` feature. Endpoint: PUT /v1/companies/{company_id}/invoices/{invoice_id}/schedule ⚠️ Fiscal guardrails — read before calling: - When an invoice can still be changed, and what to do once it cannot. (resource: beel://guardrails/invoice-state-machine) For the exhaustive rules and worked examples, call beel_docs_search.

Sets the commercial status of an invoice. Any transition other than the ones below is rejected. - **`PAID`:** from `ISSUED`, `SENT` or `OVERDUE`. - **`SENT`:** from `ISSUED`. - **`ISSUED`:** from `SENT` only, to undo a `SENT` set by mistake. - **Not set here:** issuing and voiding are fiscal acts with their own operations (`POST …/{invoice_id}/issue`, `POST …/{invoice_id}/void`), and issuing is never undone. Endpoint: PUT /v1/companies/{company_id}/invoices/{invoice_id}/status ⚠️ Fiscal guardrails — read before calling: - When an invoice can still be changed, and what to do once it cannot. (resource: beel://guardrails/invoice-state-machine) For the exhaustive rules and worked examples, call beel_docs_search.

Sets the lifecycle status of a recurring invoice template. This is how generation is paused and resumed. - **`PAUSED`:** stops automatic generation, keeping the schedule configuration intact. - **`ACTIVE`:** resumes generation and recalculates the next generation date from today. - **`COMPLETED`:** reached on its own when the schedule runs out. It cannot be set here; the body only accepts `ACTIVE` and `PAUSED`. - **Rejected transitions:** resuming a template that is already active, or one whose `pause.blocker` is still in effect. Endpoint: PUT /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/status ⚠️ Fiscal guardrails — read before calling: - How BeeL derives the AEAT invoice type, and the rules each type imposes. (resource: beel://guardrails/invoice-types) - What regime_key means, where it lives, and which combinations are rejected. (resource: beel://guardrails/regime-keys) For the exhaustive rules and worked examples, call beel_docs_search.

Skips the next scheduled invoice generation and advances the generation date to the following period. Nothing is issued. Endpoint: POST /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/skip ⚠️ Fiscal guardrails — read before calling: - How BeeL derives the AEAT invoice type, and the rules each type imposes. (resource: beel://guardrails/invoice-types) - What regime_key means, where it lives, and which combinations are rejected. (resource: beel://guardrails/regime-keys) For the exhaustive rules and worked examples, call beel_docs_search.

Sends a synthetic payload to the subscription's URL immediately, outside the normal delivery queue. Use it to verify that your endpoint is reachable and handles deliveries correctly before you rely on real events. - **Payload:** carries `"test": true` and synthetic data, and is signed like any other delivery, so it also exercises your signature check. - **Retries:** none. A failed test is not retried and does not appear in the delivery history. - **`Idempotency-Key`:** repeating the call with the same key returns the cached result without sending the test payload again. - **Result:** read `delivery_success`; a delivery your endpoint rejected is still a successful test run, not an error. Endpoint: POST /v1/accounts/{account_id}/webhooks/{webhook_id}/test

Updates how the invoices of a company are rendered and delivered: PDF template, accent colour, invoice language and email language. Only the properties present in the request body are modified, and the logo is managed through the `logo` sub-resource. The change applies to invoices rendered after it and does not alter already issued documents. Endpoint: PUT /v1/companies/{company_id}/invoice-customization

Updates the preferences of the authenticated person. Today the only mutable preference is `language`. It applies to the interface, to template names and colours in invoice customisation, and to the emails the person receives. It belongs to the person, not to a fiscal profile: the languages of invoices and of emails are separate settings of each company. Endpoint: PATCH /v1/me

Updates the tax configuration of a company. Fields you omit keep their current value; `default_main_tax`, when sent, replaces the stored one wholesale. - **Regime coherence:** the main tax and its VeriFactu regime key must be coherent. Regime key `18` (equivalence surcharge) only exists for `IVA`, so pairing it with any other regime answers `422 INVALID_REGIME_KEY_FOR_TAX_TYPE`, with `details` naming the rejected key, the tax type and the keys that type admits. - **Surcharge:** applying the surcharge without regime key `18` answers `422` `RECARGO_REQUIRES_REGIME_RE`. - **Exemption reason:** `default_exemption_reason` travels with `default_main_tax` — sending the tax without a reason clears the stored one, and sending only the reason applies it to the tax already stored. Endpoint: PUT /v1/companies/{company_id}/tax-configuration

Replaces the VeriFactu configuration of a company. - **Writable fields:** only `enabled` and `apply_by_default`, and both are required — this is a full replacement, not a partial merge. The rest of the returned configuration is resolved server-side. - **Coherence:** `apply_by_default` cannot be true while `enabled` is false, which answers `422 APPLY_BY_DEFAULT_REQUIRES_ENABLED`. ## Turning it off Setting `enabled` to false stops sending this company's invoices to AEAT and starts the deregistration of the NIF with the VeriFactu provider. It does not deactivate the company: the activation is a fact of its own for the (company, environment) pair, so the company keeps issuing in that environment and stays `ready`. Releasing the NIF — and in Live freeing it for another account — is always `DELETE /v1/companies/{company_id}/activations`. Endpoint: PUT /v1/companies/{company_id}/verifactu-configuration ⚠️ Fiscal guardrails — read before calling: - Why an issued invoice may never reach AEAT, and how to tell before issuing. (resource: beel://guardrails/verifactu-gates) For the exhaustive rules and worked examples, call beel_docs_search.

Checks a NIF or CIF against the AEAT register through VeriFactu and returns what the register says about it. It only reads the register: it creates nothing and stores no customer. - **`status`:** distinguishes a NIF found in the register from one that is syntactically correct but absent, and from a check that could not be completed because VeriFactu was unavailable — in which case the NIF is validated automatically once the service is back. - **`valid: true`:** means different things by holder. For an individual, AEAT matched NIF and name together. For a legal entity the name you sent is **not verified** at all — AEAT identifies a company by its CIF alone — so it says nothing about your name. - **`legal_name_verified`:** tells those two cases apart. - **`census_status`:** says whether an identified NIF is also deregistered or revoked. ## Invalid input - **Bad syntax is an answer, not an error:** it comes back `200` with `status: INVALID`, so a pre-validation flow never has to tell rejections apart by status code. - **A missing NIF is an error:** an absent or empty `nif` answers `422` `FIELD_BLANK`, with `details.field` naming it. Endpoint: POST /v1/nif/validate ⚠️ Fiscal guardrails — read before calling: - Why a name that does not match the census makes an invoice unsubmittable. (resource: beel://guardrails/nif-validation) For the exhaustive rules and worked examples, call beel_docs_search.

Voids an issued invoice of this company. The document is kept and its number is never reused. - **When to use it:** the operation never took place. If it did take place but with errors, issue a corrective invoice instead (`POST …/{invoice_id}/corrective`). - **`reason`:** required, at least 10 characters — it is fiscal data. - **VeriFactu:** when it is enabled for the invoice, a cancellation record is submitted to the AEAT. - **Proformas:** voiding an `ACTIVE` proforma is a plain status change with no fiscal effect — no corrective invoice, nothing submitted to the AEAT. The voided proforma is kept as the record of a rejected or withdrawn offer and stays listed. Endpoint: POST /v1/companies/{company_id}/invoices/{invoice_id}/void ⚠️ Fiscal guardrails — read before calling: - Choosing wrong here misreports to AEAT. The 30-second decision. (resource: beel://guardrails/cancel-vs-rectify) - When an invoice can still be changed, and what to do once it cannot. (resource: beel://guardrails/invoice-state-machine) For the exhaustive rules and worked examples, call beel_docs_search.