Switches an existing company (NIF) on in the mode carried in the body. The mode is always explicit and never taken from the credential's environment, so a Test key can switch a NIF on in Live. TEST is immediate and free. PROD is immediate when the account already has a card on file or an enterprise contract, and the NIF is added to the existing subscription. With no card on file it answers 402 CHECKOUT_REQUIRED, returning a checkout_url when success_url and cancel_url are supplied. Switching on in Live also requires being the billing subject of the account (403 NOT_BILLING_OWNER otherwise). Repeating the call opens no second checkout and adds no second subscription item: it returns the existing activation with already_active: true. The same Idempotency-Key sent to this route and to the nested one it replaces is the same operation, so it is replayed and never charged twice. It also cancels a pending switch-off. While that switch-off is pending the NIF is still on — it just carries an effective date — so switching it on again only removes that date, answers scheduled_deactivation_cancelled: true, and charges or credits nothing.

Endpoint: POST /v1/companies/{company_id}/activations

Cancels the active AEAT representation of a company (NIF). Until a new document is generated and signed, the company can no longer submit invoices to AEAT in production; its activation and its ability to issue non-VeriFactu invoices are untouched.

A company with no active representation is rejected with 400: cancelling is a state transition, not a delete-if-present.

Endpoint: DELETE /v1/companies/{company_id}/representation

Updates the access_level you keep over an account you provisioned. Raising it is only possible while the account is unclaimed: once its holder has taken ownership you may keep or lower your access, but only they can raise it. The level never affects billing — you pay for the account's subscription at any level. Issuing invoices on the holder's behalf with OPERATE additionally requires a signed fiscal representation from them.

Requires the manage_accounts entitlement.

Endpoint: PATCH /v1/accounts/{account_id}/access-level

Converts an accepted proforma of this company into a real invoice. Only proformas in status ACTIVE convert; one shown as EXPIRED is still ACTIVE underneath and converts too. The proforma is preserved as the record of what the customer accepted: it keeps its PRO-... number and PDF and moves to the terminal status CONVERTED.

The call creates a new STANDARD invoice in DRAFT, linked back through source_proforma_id. With issue: true that invoice is numbered and issued in the same atomic call: if issuing fails, nothing is created and the proforma stays ACTIVE. 422 CONVERSION_REQUIRES_PROFORMA when the document is not a proforma, 422 PROFORMA_NOT_CONVERTIBLE when it is not in ACTIVE, and 409 PROFORMA_ALREADY_CONVERTED when it has already been converted — a second call never creates a second invoice.

Endpoint: POST /v1/companies/{company_id}/invoices/{invoice_id}/convert-to-invoice

⚠️ 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.

Issues a single-use claim_token, and the claim_url built from it, so the account's holder can set a password and take ownership. Send email when the account has no holder yet — the person is created by this call; omit the body to re-issue the token for the holder the account already has. An email that differs from the existing holder's is rejected rather than replacing them.

Tokens last 30 days and only the last one issued is live: issuing again invalidates the previous token, so the old link stops working the moment you ask for a new one. This hands the account itself over to its holder; to add a further person to an account that already has one, invite them with POST /v1/accounts/{account_id}/invitations.

Requires the manage_accounts entitlement.

Endpoint: POST /v1/accounts/{account_id}/claim-tokens

Creates a single-use invitation for a person to join the account with the given account_role, and returns its acceptance token once — it is never readable again, so deliver it to the invitee. grants is required: send the companies a MEMBER starts with, or [] to invite them with no company access yet. Grants are only valid for MEMBER, since OWNER and ADMIN reach every company implicitly. OWNER cannot be invited — an account has exactly one owner, handed over only through PUT /v1/accounts/{account_id}/owner.

By default BeeL sends no email and you deliver the token or invitation_url yourself; set send_email to true to have the invitation emailed to invited_email as well.

Endpoint: POST /v1/accounts/{account_id}/invitations

Registers an HTTPS endpoint to receive event notifications for the events listed in events. The signing secret is returned only in this response and never again; store it before discarding the body.

An account holds at most 10 active subscriptions; creating an eleventh is rejected. Registering the same URL twice creates two subscriptions, and the endpoint then receives each event twice.

Endpoint: POST /v1/accounts/{account_id}/webhooks

Creates a company (NIF) under the account in the path and, unless activate is false, switches it on in aeat_environment and seeds its three default invoice series (ordinary, simplified, corrective). The optional numbering block decides the code, format, counter reset and starting number those series are born with, and is only accepted when the request activates the company.

A NIF that already exists in the account is rejected with 409; the response carries the existing error.details.company_id. This endpoint never switches an existing company on and never starts a charge: creating a production NIF on an account without billing is rejected with 402 and no checkout is opened. Switching an existing NIF on is POST /v1/companies/{company_id}/activations. The company is created under the account the request resolves to, and the NIF is registered in the name of that account's holder, never in the name of the caller.

Endpoint: POST /v1/accounts/{account_id}/companies

⚠️ Fiscal guardrails — read before calling:

• Which company an operation acts on, and how that is selected. (resource: beel://guardrails/multi-nif)

• Why a name that does not match the census makes an invoice unsubmittable. (resource: beel://guardrails/nif-validation)

• 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.

Issues a corrective invoice that amends the invoice in the path. It is a new fiscal document with its own number, not an edit of the original. A TOTAL rectification leaves the original VOIDED; a PARTIAL one leaves it RECTIFIED and requires the adjustment lines, while TOTAL copies the original lines negated when they are omitted.

Only an ordinary or a simplified invoice in ISSUED, SENT, PAID, OVERDUE or RECTIFIED can be rectified. Rectifying a corrective fails with 422 CORRECTIVE_NOT_RECTIFIABLE — to fix an erroneous corrective, issue another one against the original invoice. A VOIDED invoice is no longer rectifiable, so a second TOTAL against the same invoice fails with 422 INVOICE_NOT_CORRECTIBLE_IN_CURRENT_STATUS; several PARTIAL correctives are allowed.

Omitting series_id numbers the document in the company's default corrective series, never in the series of the original, which is an ordinary or simplified one. That default is never created for you: if the company has none, the request fails with 422 SERIES_DEFAULT_NOT_FOUND; GET /v1/configuration/series/defaults-status reports which default is missing.

Endpoint: POST /v1/companies/{company_id}/invoices/{invoice_id}/corrective

⚠️ Fiscal guardrails — read before calling:

• Choosing wrong here misreports to AEAT. The 30-second decision. (resource: beel://guardrails/cancel-vs-rectify)

• How BeeL derives the AEAT invoice type, and the rules each type imposes. (resource: beel://guardrails/invoice-types)

• How a line states its price, and which field combinations are rejected. (resource: beel://guardrails/invoice-lines)

• When an invoice can still be changed, and what to do once it cannot. (resource: beel://guardrails/invoice-state-machine)

• 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.

Creates a new customer under this company (NIF). An Idempotency-Key identifies the same operation on the deprecated flat route, so a retry that switches route replays instead of creating twice.

Endpoint: POST /v1/companies/{company_id}/customers

⚠️ 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.

Creates up to 500 customers of this company (NIF) in a single call. The operation is atomic: if any customer fails validation the whole batch is rejected with 422 BULK_VALIDATION_ERROR and nothing is persisted.

With dry_run=true the batch is only validated — tax identifiers against the AEAT register, duplicates inside the batch and against the existing customers, field formats — nothing is written and the answer is 200. With dry_run=false, the default, validation is followed by creation and the answer is 201. Both modes return the same per-record report, so a dry run and a real run are read the same way.

Endpoint: POST /v1/companies/{company_id}/customers/bulk

⚠️ 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.

Creates an invoice under this company (NIF); the issuer data is taken from the company in the path. With issue_directly: true the invoice is numbered and issued in the same call, and verifactu.submission_status comes back as PENDING, since submission to AEAT is asynchronous: a 2xx means accepted for submission, never registered with AEAT.

A proforma (type: PROFORMA) is a non-fiscal document: it is created directly in its only working state ACTIVE, numbered PRO-... from the non-fiscal series, and issue_directly does not apply to it. To copy an existing invoice into a new draft use POST …/invoices/derivations, which carries neither type, nor recipient, nor lines.

Endpoint: POST /v1/companies/{company_id}/invoices

⚠️ Fiscal guardrails — read before calling:

• How BeeL derives the AEAT invoice type, and the rules each type imposes. (resource: beel://guardrails/invoice-types)

• How a line states its price, and which field combinations are rejected. (resource: beel://guardrails/invoice-lines)

• What regime_key means, where it lives, and which combinations are rejected. (resource: beel://guardrails/regime-keys)

• Why a name that does not match the census makes an invoice unsubmittable. (resource: beel://guardrails/nif-validation)

• Why an issued invoice may never reach AEAT, and how to tell before issuing. (resource: beel://guardrails/verifactu-gates)

• 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.

Applies one operation — ISSUE or STATUS — to up to 50 invoices of this company and reports, invoice by invoice, which succeeded and which failed.

Not atomic: each invoice is processed in its own transaction, and since issuing is irreversible, the ones already issued stay issued if a later one fails. Downloading PDFs, sending email and exporting are not operations of this batch: use pdf-archive, deliveries and exports.

Endpoint: POST /v1/companies/{company_id}/invoices/batches

Sends one email carrying the PDFs of up to 200 invoices of this company as attachments, to the addresses given in recipients. At least one recipient is required: no address is inferred from any profile. Invoices whose PDF cannot be attached are reported in failures and the message is still sent with the rest.

Endpoint: POST /v1/companies/{company_id}/invoices/deliveries

Creates a draft invoice derived from an existing invoice of this company, named in from_invoice_id with mode: DUPLICATE. Recipient, lines, payment method, series and observations are copied; number, status, dates, VeriFactu data and PDF are reset. The source invoice is not modified.

The series — the one sent in series_id or the source's, inherited — is validated against the type of the copy, which is not always the source's: the copy of a CORRECTIVE is born STANDARD. An incompatible series fails with 422 SERIES_INCOMPATIBLE_DOC_TYPE.

Endpoint: POST /v1/companies/{company_id}/invoices/derivations

⚠️ 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.

Creates a new product or service in the catalog of this company (NIF).

Endpoint: POST /v1/companies/{company_id}/products

Creates up to 100 products in the catalog of this company (NIF). The operation is partial: each product is processed and reported independently, so a row the domain rejects — a rate the law does not allow, a duplicate code — comes back inside the report while the rest are created.

Endpoint: POST /v1/companies/{company_id}/products/bulk

Creates a recurring invoice template under this company (NIF) with its template data (lines, recipient, series, payment) and its recurrence. Generation runs monthly on day_of_month, from start_date until end_date if one is given.

A start_date in the past is accepted and stored, but never anchors generation backwards: next_generation moves to the first upcoming day_of_month and the missed periods are not generated.

Endpoint: POST /v1/companies/{company_id}/recurring-invoices

⚠️ 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.

Creates a recurring invoice template of this company taking its lines, recipient, series and payment data from the invoice named in from_invoice_id, so only the recurrence has to be described. The source invoice is not modified.

Omitting verifactu_enabled inherits the value of the source invoice; send it explicitly to override that inheritance.

Endpoint: POST /v1/companies/{company_id}/recurring-invoices/derivations

⚠️ 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.

Creates an invoice series under a company (NIF). The series code must be unique within the company — a code already taken answers 409 — and its format and counter_reset must be able to tell reset periods apart: a MONTHLY reset needs {MM} and a year token, an ANNUAL reset needs a year token.

The first series created for a company is automatically marked as default.

Endpoint: POST /v1/companies/{company_id}/series

⚠️ 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.

Switches the company (NIF) off in the mode given by environment; the other mode is untouched. The activation is sealed rather than deleted, so its history survives; after the switch-off takes effect the NIF can neither issue nor correct invoices in that mode until it is switched on again, and in Live that sealing is what releases the NIF for another account. In Live the switch-off is scheduled, not immediate: the cycle is paid up front, so the response carries an effective_at and the NIF keeps invoicing until then. Nothing is refunded. effective_at is the end of the current billing cycle, unless the NIF was switched on within that same cycle, in which case it is the end of the next one. TEST, and PROD under an enterprise contract, are immediate and answer with no effective_at. Repeating the call on a mode whose switch-off is already pending returns the same date with already_scheduled: true, and switching off a mode that was never on is a silent no-op. Switching off in Live requires being the billing subject of the account.

Endpoint: DELETE /v1/companies/{company_id}/activations

Revokes a PENDING invitation, so its acceptance link stops working. An invitation already accepted, revoked or expired cannot be revoked, and answers 404 without disclosing which of the three it is. Revoking does not remove the invitation from the list.

Endpoint: DELETE /v1/accounts/{account_id}/invitations/{invitation_id}

Removes a member's access to the account. The account's last OWNER cannot be removed.

Endpoint: DELETE /v1/accounts/{account_id}/members/{member_id}

Revokes a MEMBER's access to one company. Their grants over the account's other companies are left as they were.

Endpoint: DELETE /v1/accounts/{account_id}/members/{member_id}/grants/{company_id}

Permanently deletes a webhook subscription. No further events are delivered to its URL. To stop deliveries reversibly, set active to false instead.

Endpoint: DELETE /v1/accounts/{account_id}/webhooks/{webhook_id}

Removes a company (NIF) from the account: it stops appearing and stops being billed. Invoices already issued are retained, but the company-scoped API can no longer resolve them once the NIF is removed.

A NIF activated in Live cannot be removed (409 COMPANY_ACTIVE_IN_PRODUCTION), and neither can one holding any invoice in Live — issued, draft or proforma (409 COMPANY_HAS_INVOICES) — nor the account's primary NIF (400 CANNOT_DELETE_PRIMARY). Switching off in Live is scheduled to the end of the paid cycle, so the removal only becomes possible once that takes effect. NIFs never activated, or activated only in Test, are removed right away, and invoices in Test never block.

Without an Idempotency-Key, a retry after a timeout answers 403 instead of the original 204.

Endpoint: DELETE /v1/companies/{company_id}

⚠️ Fiscal guardrails — read before calling:

• Which company an operation acts on, and how that is selected. (resource: beel://guardrails/multi-nif)

For the exhaustive rules and worked examples, call beel_docs_search.

Deletes a customer of this company (NIF) that has no invoices. The customer is retained internally for tax record-keeping purposes, but is no longer exposed by the API: subsequent requests to it return 404, and it is never included in the customer list, under any value of the active filter. Its NIF or alternative identifier is released, so a new customer may be created with the same identifier.

A customer that has invoices cannot be deleted and answers 409 CLIENT_HAS_INVOICES. To stop using a customer, update it with active set to false instead of deleting it.

Endpoint: DELETE /v1/companies/{company_id}/customers/{customer_id}

Deletes the customers listed in ids from this company (NIF). The operation is partial: the customers that can be deleted are deleted, and the rest keep their place in customers_deletion with the status that explains why. That is why it answers 200 with a body instead of 204, and why it answers 200 even when no row could be deleted.

Each deletion has the same semantics as DELETE /v1/companies/{company_id}/customers/{customer_id}: the customer is retained internally for tax record-keeping purposes but is no longer exposed by the API, its identifier is released for reuse, and invoices already issued to it keep their own copy of the recipient's details. Deleting is not deactivating: deleting frees the identifier, so the same NIF can be registered again, while PATCH with active: false leaves the customer where it is with its NIF still taken. A customer that has invoices cannot be deleted and comes back with row status HAS_INVOICES.

Endpoint: DELETE /v1/companies/{company_id}/customers/bulk

Deletes a draft invoice of this company. The record is marked as deleted rather than removed. An issued invoice is never deleted: it is voided with POST …/{invoice_id}/void, which leaves the fiscal trail.

If the draft came from converting a proforma (source_proforma_id present), deleting it returns that proforma from CONVERTED to ACTIVE, editable and convertible again. Voiding or rectifying an issued invoice does not return its proforma; only deleting the draft does.

Endpoint: DELETE /v1/companies/{company_id}/invoices/{invoice_id}

⚠️ 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.

Removes the scheduling of an invoice, returning it to a plain draft. Idempotent: an invoice that is not scheduled answers 204 all the same. Unlike the PUT, it does not require the scheduled_invoices feature.

Endpoint: DELETE /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)

• Choosing wrong here misreports to AEAT. The 30-second decision. (resource: beel://guardrails/cancel-vs-rectify)

For the exhaustive rules and worked examples, call beel_docs_search.

Removes the logo of a company (NIF). Invoices rendered afterwards carry no logo, and already issued documents are unchanged. Deleting an absent logo also returns 204.

Endpoint: DELETE /v1/companies/{company_id}/logo

Deletes a product from the catalog of this company (NIF).

Endpoint: DELETE /v1/companies/{company_id}/products/{product_id}

Deletes the products listed in ids from the catalog of this company (NIF), up to 100 IDs per request; send several requests for more. The operation is partial: the response reports which products were deleted and which failed, which is why it answers 200 with a body instead of 204.

Endpoint: DELETE /v1/companies/{company_id}/products/bulk

Permanently deletes a recurring invoice template of this company (NIF) and cancels any pending scheduled generations. Invoices already generated from it are not affected.

Endpoint: DELETE /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.

Soft-deletes an invoice series, deactivating it first if it is active. The code is not released: it stays taken after the deletion because it identifies the invoices already issued under it, so recreating a series with the same code answers 409 SERIES_CODE_DUPLICATED.

A default series cannot be deleted while another active series of the same document type exists — promote that other one first. If it is the only series of its type it is deleted and the type is left with none, a valid state in which issuing without an explicit series_id answers SERIES_DEFAULT_NOT_FOUND.

Endpoint: DELETE /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.

Disconnects the payment provider connection (stripe) of a NIF (company) that your account owns or manages. BeeL deletes the stored credentials and auto-invoicing stops at once: charges arriving afterwards are ignored and produce no invoice. Already-issued invoices are not affected.

The authorization the holder granted at the provider is not revoked on the provider's side. To withdraw it, the holder must remove BeeL's access from the provider's own dashboard (in Stripe, Settings → Connected applications).

Endpoint: DELETE /v1/companies/{company_id}/payment-connections/{provider}

Returns a presigned URL, valid for 5 minutes, to download the representation PDF of a company (NIF). While the document is unsigned it serves the generated one; once the signed copy has been submitted it serves that.

A company that has not generated the document yet is rejected with 400.

Endpoint: GET /v1/companies/{company_id}/representation/document

Ends the management relationship over an account you provisioned: you lose access to it and its NIFs stop counting towards your billable usage from the next billing cycle. The account holder keeps the account, its NIFs and its invoices, and becomes responsible for their own subscription. Nothing is deleted or anonymised.

It is reversible only while the account stays unclaimed: provisioning the same email again reactivates it (see POST /v1/accounts), and only the manager who ended the relationship can do so. Once the holder claims the account it is theirs, and getting the management back needs their consent, not just their email address.

Requires the manage_accounts entitlement.

Endpoint: DELETE /v1/accounts/{account_id}/management

Ensures the company (NIF) has a default invoice series for STANDARD, SIMPLIFIED and CORRECTIVE in the current environment, and returns the resulting set. The request takes no body: the desired end state is one default per document type, so repeating it changes nothing.

A document type that already has a default keeps it, and it is returned unchanged. A missing one is created with code F, S or R and format {CODIGO}-{YYYY}-{NUM:4}, active and marked as default — unless that code is already taken by another series, in which case the type is omitted from the response and is left with no default.

Endpoint: PUT /v1/companies/{company_id}/series/defaults

⚠️ 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.

Builds a draft invoice from a payment event that could not be invoiced automatically, applying the same recipient resolution and tax treatment the automatic flow would have applied, under the NIF in the path. The document is left as a draft: it is not issued, not numbered against the series and not emailed — issue it yourself once it is right.

Only events that produced no invoice can produce a draft; otherwise the request returns 400. If invoicing rules reject the resulting document the request returns 422 and no draft is created.

Endpoint: POST /v1/companies/{company_id}/payment-connections/{provider}/events/{event_id}/draft

Runs the generation of this recurring template immediately, out of its schedule. It is a fiscal act: the generated invoice consumes numbering from the series of the template and, when the template says so, is issued and sent.

It brings the upcoming occurrence forward — it does not add one. The call consumes the period that was pending: the invoice is created now and next_generation advances one period. Generating manually, skipping and letting the scheduler run each consume exactly one occurrence, so a monthly template still produces twelve invoices a year however you mix the three.

For an extra invoice outside the calendar, do not use this endpoint: create a normal invoice, or derive a draft from one the template already generated with POST /v1/companies/{company_id}/invoices/derivations. Either way the schedule stays where it was.

Endpoint: POST /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/generate

⚠️ 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.

Generates the unsigned AEAT representation PDF of a company (NIF), which is then downloaded from GET /v1/companies/{company_id}/representation/document, signed digitally and returned through POST /v1/companies/{company_id}/representation/submit.

The fiscal identity of the company must be complete before the document can be produced; an incomplete one is rejected with 400 naming what is missing. A company that already holds an active representation is rejected too: cancel it first.

Endpoint: POST /v1/companies/{company_id}/representation

Returns one account you provisioned, with the same shape the list returns: its lifecycle status, the access_level you hold, the state of its claim link and its company_id when the account holds exactly one NIF.

Endpoint: GET /v1/accounts/{account_id}

Returns one recorded email with its message body (HTML and plain text), its attachments and, for batch emails, the invoices it carried.

The body is fetched live and is only available while the message has a provider message id and the provider still retains it; otherwise body_available is false and html_body / text_body are null. An email that never left — QUEUED or REJECTED — has no body for that reason.

Endpoint: GET /v1/accounts/{account_id}/emails/{email_id}

Returns, for each related entity id given, how many emails the history holds for it, the status of the most recent one and when it was sent. Lets you show the state of an entity's email without loading its full history.

last_status carries whatever the latest attempt ended in, REJECTED and QUEUED included, so a count above zero does not mean an email reached anyone. Ids with no associated emails are omitted from the response rather than returned with count 0.

Endpoint: GET /v1/accounts/{account_id}/email-indicators

Returns one invitation of the account, with the same shape the list returns. An invitation stays readable for its whole life: ACCEPTED, REVOKED and EXPIRED ones are returned with their status, because the record is the trail of who was granted access to the account's fiscal data and revoking it does not erase it.

Endpoint: GET /v1/accounts/{account_id}/invitations/{invitation_id}

Returns one member of the account, with the same shape the list returns.

Endpoint: GET /v1/accounts/{account_id}/members/{member_id}

Returns the full detail (bodies and headers) of a request made by you, with any of your API keys in this environment — including one made with a key other than the one you are authenticating with, because the axis is the person, not the individual credential. The {account_id} in the path authorizes the call; it does not widen what you can see.

404 if the request does not exist, was made by another user (including another user of this same account), or belongs to the other environment.

This is the widest read the logs:read scope opens: it returns the bodies and headers that any key of yours exchanged in this environment, so a key holding only logs:read reads the traffic of your privileged keys too. Grant it accordingly.

Endpoint: GET /v1/accounts/{account_id}/request-logs/{request_id}

Returns how many accounts you have provisioned and the billable count that follows from them — the figure behind your offline B2B invoice. The billable unit is the provisioned account, not the real NIF: every account you provision counts as one, empty and unclaimed ones included.

Usage is a property of the provisioner, not of each provisioned account, so account_id here is your own account; any other id returns 404.

Requires the manage_accounts entitlement.

Endpoint: GET /v1/accounts/{account_id}/usage

Returns a single webhook subscription. The signing secret is never included.

Endpoint: GET /v1/accounts/{account_id}/webhooks/{webhook_id}

Returns the identity and activation state of a company (NIF): its fiscal data, whether it is switched on in Test and in Live, and its VeriFactu registration state.

Its invoice series are not part of this response: read them from GET /v1/companies/{company_id}/series.

Endpoint: GET /v1/companies/{company_id}

⚠️ Fiscal guardrails — read before calling:

• Which company an operation acts on, and how that is selected. (resource: beel://guardrails/multi-nif)

For the exhaustive rules and worked examples, call beel_docs_search.

Retrieves the complete details of a customer of this company (NIF).

Endpoint: GET /v1/companies/{company_id}/customers/{customer_id}

Reports, for each DocumentType used by automatic invoicing flows, whether the company (NIF) has a default invoice series and which one. A document type with no default cannot be issued without naming a series_id explicitly, and automatic flows skip it with failure.payment.skip.missing_default_series.

The environment is resolved from the request context and takes no input.

Endpoint: GET /v1/companies/{company_id}/series/defaults

⚠️ 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.

Returns the VAT and IRPF summary of the invoices issued under this company (NIF) over the requested period, together with the annual IRPF projection and its progressive bracket breakdown. The period defaults to the current month and may not exceed 365 days; a longer or inverted range answers 400 naming the fault in details.reason.

Endpoint: GET /v1/companies/{company_id}/fiscal-summary

Retrieves the full details of an invoice of this company (NIF).

Endpoint: GET /v1/companies/{company_id}/invoices/{invoice_id}

⚠️ 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.

Returns how the invoices of a company (NIF) are rendered and delivered: PDF template, accent colour, invoice language, email language and current logo. Customization is a per-NIF property, so each company of the account carries its own.

The catalogue of available templates and suggested colours is served by GET /v1/invoice-customization-options.

Endpoint: GET /v1/companies/{company_id}/invoice-customization

Returns a temporary pre-signed URL to download the invoice PDF. The URL expires in five minutes and only allows GET.

A 202 with no body means the PDF is still being generated; poll this endpoint until it answers 200. A draft has no fiscal PDF and answers 400 INVOICE_NOT_ISSUED_NO_PDF: issue it, or use …/pdf/preview.

Endpoint: GET /v1/companies/{company_id}/invoices/{invoice_id}/pdf

Returns a temporary pre-signed URL to a preview image (WebP) of the invoice, suitable for inline rendering. The image is generated and cached on first request, so a later call returns the cached image. The URL expires in five minutes and only allows GET.

Endpoint: GET /v1/companies/{company_id}/invoices/{invoice_id}/preview

Returns the date and generation mode currently scheduled for this invoice. An invoice with no scheduling answers 404: the sub-resource does not exist yet. To move only the date, read the current generation_mode here and send it back on the PUT.

Endpoint: GET /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)

• Choosing wrong here misreports to AEAT. The 30-second decision. (resource: beel://guardrails/cancel-vs-rectify)

For the exhaustive rules and worked examples, call beel_docs_search.

Returns whether a company (NIF) can issue its STANDARD invoice right now in the environment of the request, and the blockers that stop it otherwise. ready is true only when blockers is empty. Readiness is a per-NIF property, evaluated independently for each company of the account.

Issuing any fiscal document requires the company to be activated in the environment of that document, whether or not it goes to VeriFactu. The VeriFactu capability chain — AEAT census and signed representation — is additionally demanded only when the company applies VeriFactu by default, the same derivation invoice creation uses when verifactu_enabled is omitted; a company with VeriFactu off is ready with a NIF, a default series and an activation. Issuing an invoice with an explicit verifactu_enabled: true still enforces the full chain at emission time regardless of this answer, and the separate verifactu block reports that chain independently of the setting.

This does not evaluate the account's quota or subscription, nor the payload of any particular invoice.

Endpoint: GET /v1/companies/{company_id}/issuing-readiness

⚠️ Fiscal guardrails — read before calling:

• Which company an operation acts on, and how that is selected. (resource: beel://guardrails/multi-nif)

For the exhaustive rules and worked examples, call beel_docs_search.

Retrieves a single payment event of the NIF's connection, including the outcome of its automatic invoicing and, when it failed, the stable failure code you can act on.

An event that does not belong to this NIF's connection returns 404, the same answer an event that does not exist gets, so an event of another NIF is never disclosed.

Endpoint: GET /v1/companies/{company_id}/payment-connections/{provider}/events/{event_id}

Retrieves the details of a product of this company (NIF).

Endpoint: GET /v1/companies/{company_id}/products/{product_id}

Retrieves the full details of a recurring invoice template of this company (NIF), including its schedule, template lines and next generation date.

Endpoint: GET /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.

Returns the invoices previously generated from this recurring template, including their status and generation dates.

Endpoint: GET /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/history

⚠️ 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.

Returns the invoice that would be produced by the next generation of this recurring template, computed from the current issuer, recipient and series data. Nothing is persisted and no numbering is consumed.

Endpoint: GET /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/next-occurrence

⚠️ 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.

Returns the state of the AEAT fiscal representation of a company (NIF): whether the document has been generated, signed and submitted, and whether AEAT accepted it or it was cancelled.

A company that never started the process is not an error: it answers 200 with the NOT_STARTED state, so polling this endpoint is always safe.

Endpoint: GET /v1/companies/{company_id}/representation

Returns one invoice series of a company (NIF), with its code, format, counter state, document type and whether it is the default of that type.

Endpoint: GET /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.

Returns the tax configuration of a company (NIF): its default tax regime with the default main percentage and regime key, plus its IRPF and equivalence surcharge settings.

The catalogue of tax types this configuration draws from is not company data and lives outside this resource.

Endpoint: GET /v1/companies/{company_id}/tax-configuration

Retrieves the VeriFactu configuration of this company (NIF). The configuration belongs to the NIF, so the NIF in the path is what decides which one is returned.

Endpoint: GET /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.

Returns the identity of the authenticated principal: the account the credential belongs to, the person's email, name, logo and interface language, and a description of the credential itself. Unlike every other operation, it requires no scope — any valid credential resolves, so a 200 confirms the credential works and tells you which account it belongs to, and a 401 that it does not.

account_id identifies who the credential belongs to, not what it is currently pointed at: selecting a different company with BeeL-Active-Company does not change it. name resolves as trade_name ?? legal_name of the active fiscal profile and is null until onboarding creates one. Responses are never cached (Cache-Control: no-store).

credential describes the credential the call was authenticated with — its type, the environment it operates on and the permissions it holds — so a client can adapt what it offers instead of discovering the limits through a 403.

Endpoint: GET /v1/me/identity

Opens an authorization session so the holder of a NIF (company) your account manages can connect a payment provider (stripe), and returns the authorization_url where they authorize it. Once they do, BeeL's callback finalizes the connection and redirects back to the return_url of your portal, if you supplied one, with the parameters described under return_url.

The connection is created only when the holder authorizes, so it does not appear in GET /v1/companies/{company_id}/payment-connections until then. It is sealed under the NIF in the path, so auto-invoicing issues under that NIF.

The NIF must be activated in the mode of your API key (beel_sk_test_* → Test, beel_sk_live_* → Live); otherwise the request answers 400 COMPANY_NOT_ACTIVATED_IN_ENVIRONMENT and no authorization_url is issued, because without activation there is no invoice series or tax configuration to invoice with. Test and Live activations are independent — a NIF activated in one mode still needs activating in the other.

Endpoint: POST /v1/companies/{company_id}/payment-connections/authorizations

Finalizes a draft invoice of this company: assigns its definitive number from the configured series and makes it immutable. Irreversible — an issued invoice is corrected with a corrective invoice or voided, never edited.

PDF and VeriFactu submission are asynchronous: a 200 means accepted for submission, never registered with AEAT.

Endpoint: POST /v1/companies/{company_id}/invoices/{invoice_id}/issue

⚠️ 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)

• 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.

Returns the emails the system recorded on behalf of the account in the path: invoice deliveries, verification, onboarding. Every attempt is recorded, not only the ones that went out — an email stopped by policy is listed with status REJECTED, and one accepted but not dispatched yet as QUEUED, rather than being omitted.

Results are ordered by sent_at descending (configurable via sort_by / sort_order) and can be narrowed by type, status, recipient and related_entity_id. sent_at is the moment the message was handed over, so it is absent while an email is still QUEUED. The account is the one named in the path; the environment is not, and comes from the credential. This operation only reads the history; it does not send or resend anything.

Endpoint: GET /v1/accounts/{account_id}/emails

Lists the invitations sent to join the account, whatever their status. Accepted, revoked and expired invitations stay in the list: the record is the trail of who was granted access to the account's fiscal data.

Endpoint: GET /v1/accounts/{account_id}/invitations

Lists the companies (NIFs) granted to a MEMBER and the access_level of each. Empty for OWNER and ADMIN, who reach every company of the account implicitly and hold no grants.

Endpoint: GET /v1/accounts/{account_id}/members/{member_id}/grants

Lists the people with access to the account, each with their account_role and, for MEMBERs, the companies (NIFs) granted to them. The whole list is returned; it is not paginated.

Endpoint: GET /v1/accounts/{account_id}/members

Returns the history of public API requests made by you, with any of your API keys in this environment — not only the key you are authenticating with. The axis is the person, not the individual credential: a second key of yours sees the same history, and narrowing it to one key is a filter (api_key_id), not the default.

It is still not the account's traffic: requests made by other users of the same account, or by their API keys, are never returned. The {account_id} in the path authorizes the call; it does not widen what you can see.

Only auth_type=API_KEY traffic is recorded.

Environment is not a filter: results are always scoped to the environment of the credential you authenticate with — a beel_sk_test_* key sees the test traffic of all your test keys, a beel_sk_live_* key the live traffic of all your live ones. To see the other environment, use a key from that environment.

Cursor pagination: navigate with the opaque cursor returned in next_cursor / prev_cursor; there is no jump to an arbitrary page N. The window defaults to the last 30 days; narrow or move it with from/to.

Endpoint: GET /v1/accounts/{account_id}/request-logs

Returns the accounts you provisioned, each with its lifecycle status (PROVISIONED → CLAIMED → ACTIVE), the access_level you hold over it and the state of its claim link. Newest first. Narrow the list with status, or look one up by the external_ref you assigned when provisioning it.

Endpoint: GET /v1/accounts

Returns the delivery attempts of this subscription, newest first. Each entry records one attempt with the response it got, so a retried event appears once per attempt. Narrow it with event_type, or with event_id to follow a single event across its attempts.

Endpoint: GET /v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries

Returns the webhook subscriptions of the account in the path, active and inactive alike. Every member of the account sees the same list: who registered a subscription is authorship, not visibility. The signing secrets are never included.

Endpoint: GET /v1/accounts/{account_id}/webhooks

Returns a page of the companies (NIFs) belonging to the account in the path, ordered with the primary company first. search filters case-insensitively on NIF, legal name and trade name; include=readiness adds each company's issuing-readiness block. The response is always paginated, and an account with no companies yet returns an empty page rather than an error.

The invoice series of each company are not part of this response: read them from GET /v1/companies/{company_id}/series.

Endpoint: GET /v1/accounts/{account_id}/companies

⚠️ Fiscal guardrails — read before calling:

• Which company an operation acts on, and how that is selected. (resource: beel://guardrails/multi-nif)

For the exhaustive rules and worked examples, call beel_docs_search.

Returns a paginated list of the customers of this company (NIF), with optional filters. Only the customers of the company in the path are returned.

Endpoint: GET /v1/companies/{company_id}/customers

Returns a paginated list of the invoices of this company (NIF), filterable by status, type, series, customer, date range and free text. Only the documents of the company in the path are returned.

Endpoint: GET /v1/companies/{company_id}/invoices

⚠️ 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.

Returns the payment provider connections of a NIF (company) your account owns or manages, with the provider-side account each one points at and its status. Use it to check whether a NIF you provisioned has completed its connection; a NIF with none answers 200 with an empty list.

Test and Live connections are independent, so only the ones living in the mode of the key you ask with are returned; environment states which.

Endpoint: GET /v1/companies/{company_id}/payment-connections

Lists the payment events received through the payment provider connection of a NIF (company) that your account owns or manages, most recent first. Use it to audit the charges that produced an invoice and to find the ones that did not.

Events belong to the connection, not to the NIF directly. The {provider} segment picks the connection of the NIF in the path, and only the events of that connection are returned; an event of another NIF of the same account is never reachable from here.

If the NIF has no connection for the provider, returns 404.

Endpoint: GET /v1/companies/{company_id}/payment-connections/{provider}/events

Returns a paginated list of the products/services of this company (NIF), with optional filters.

Searching is ?q= on this collection: there is no separate search path. q matches the name, the code and the description, so it returns at least everything the withdrawn GET /v1/products/search returned, in the paginated envelope of this list.

Endpoint: GET /v1/companies/{company_id}/products

Lists the recurring invoice templates of this company (NIF), with filters and pagination. Only the templates of the company in the path are returned.

Endpoint: GET /v1/companies/{company_id}/recurring-invoices

⚠️ 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.

Returns the invoice series of a company (NIF), optionally filtered by active and by document_type — a document_type filter always includes the UNASSIGNED series, which are compatible with any type.

Pagination is opt-in here: send page and/or limit to receive a single page plus a data.pagination block with the totals. Omit both and the response carries the full list in data.series and no pagination block.

Endpoint: GET /v1/companies/{company_id}/series

⚠️ 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.

Returns, for each company (NIF) of the account, how many fiscal documents it has issued and when it last issued one. Drafts, scheduled invoices and proformas are not counted; a rectifying invoice counts as a document of its own, and a voided invoice counts only when a live rectifying invoice compensates it.

The count is therefore not monotonic — voiding an uncompensated invoice lowers it and moves last_invoice_at backwards — so it is not usable as a synchronisation cursor.

Endpoint: GET /v1/accounts/{account_id}/companies/stats

Returns the PDF templates a NIF can be rendered with. For each one, the code to send as template_type in PUT /v1/companies/{company_id}/invoice-customization, plus a name and a short description translated into the language of the user the credential belongs to.

The accepted values are already in the template_type enum; what this operation adds are the readable labels, so you do not have to show MODERN_TABLE to a person. The catalogue is identical for every account and every NIF, so it is not nested under one.

Endpoint: GET /v1/invoice-customization-options

Returns the tax regimes and percentages that Spanish law allows on an invoice: VAT (mainland), IGIC (Canary Islands), IPSI (Ceuta and Melilla), the withholding (IRPF) percentages, the equivalence surcharge that corresponds to each VAT rate, and the exemption reasons with the classification each one implies.

The catalogue is the same for every credential and does not depend on any account or on any NIF, so the operation takes no identifier and works before the first NIF exists. Use it to validate a rate before sending it, or to build your own picker instead of hard-coding the percentages.

VAT lists 4, 5, 10 and 21, and deliberately not 0. Under VAT (and IPSI) a 0 % is not a rate but the exemption/non-subject sentinel, and on its own it says nothing: a 0 % line is only valid together with an exemption_reason, which this same response publishes under exemption_reasons. IGIC does list 0: there it is the real "Tipo Cero" and needs no reason. The 5 % VAT rate (RD-ley 11/2022) is kept even though it no longer applies to new operations, because correctives and late filings for those periods still need it.

Endpoint: GET /v1/tax-types

Changes a member's account_role between ADMIN and MEMBER. OWNER is not an assignable value here — an account has exactly one owner, and ownership is handed over only through PUT /v1/accounts/{account_id}/owner, which promotes the new owner and steps the current one down in the same operation. The account's last OWNER cannot be demoted.

Endpoint: PATCH /v1/accounts/{account_id}/members/{member_id}

Updates the fields present in the body — url, events, active — and leaves the rest untouched. Sending events replaces the whole list, it does not add to it, so an event left out of it stops being delivered.

The signing secret is not touched here; rotate it with POST /v1/accounts/{account_id}/webhooks/{webhook_id}/secret. Setting active to false stops deliveries without discarding the delivery history.

Endpoint: PATCH /v1/accounts/{account_id}/webhooks/{webhook_id}

Updates the editable fields of a company (NIF); the set is the one UpdateCompanyRequest declares. nif, entity_type and legal_form are immutable once set, and changing legal_name requires the NIF to pass an AEAT census re-validation — which for a company checks the CIF only, so it cannot fail because of the name sent.

Once the company is activated in Live, a test credential may only write the fields that affect how the invoice looks: logo_url, invoice_accent_color, invoice_template_type, invoice_language, email_language and additional_info. Any other field describes the real business — fiscal address, legal representative, bank details, contact data, IAE, activity start date, payment term — and answers 422 FISCAL_IDENTITY_LIVE_ONLY from Test, since the company is a single record shared by both modes. A company not activated in Live accepts the whole body from Test, and sending a field its current value is never a change.

The 200 returns CompanyData, which carries the identity of the NIF and not the rest of the request body. The rendering fields are read back from GET /v1/companies/{company_id}/invoice-customization; the remaining ones are write-only. The invoice series are read from GET /v1/companies/{company_id}/series.

Endpoint: PATCH /v1/companies/{company_id}

⚠️ Fiscal guardrails — read before calling:

• Which company an operation acts on, and how that is selected. (resource: beel://guardrails/multi-nif)

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 customer as it is. A field sent as null is cleared, which is different from omitting it (see PatchCustomerRequest).

This is the canonical way to edit a customer. There is no PUT of full replacement under the company, which would clear the fields you omit.

Endpoint: PATCH /v1/companies/{company_id}/customers/{customer_id}

Updates only the fields present in the body, leaving every other field of the invoice as it is. Only a draft invoice can be modified: an issued one is amended with a corrective invoice or voided.

Changing series_id never moves the invoice to another NIF: a series of another company is not visible from here.

Endpoint: PATCH /v1/companies/{company_id}/invoices/{invoice_id}

⚠️ 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.

Updates only the fields present in the body, leaving every other field of the product as it is — in particular main_tax, irpf_rate and equivalence_surcharge_rate.

A field sent as null is cleared, which is different from omitting it (see PatchProductRequest). This is the only update verb of the canonical form: the total replacement PUT /v1/products/{product_id}, which reset the omitted fields to their creation defaults, is not carried over.

Endpoint: PATCH /v1/companies/{company_id}/products/{product_id}

Updates only the fields present in the body, leaving every other field of the recurring invoice as it is — in particular the recipient, which survives a change of lines. A field sent as null is cleared, which is different from omitting it.

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. A field sent as null clears it, which only description supports. The numbering fields — code, format, counter_reset and initial_number — are rejected once the series has issued invoices.

default_series 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.

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. Send email 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. Send tax_profile 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 sets the access you retain over the account and defaults to NONE; OPERATE requires a tax_profile. Provisioning is idempotent by external_ref: resending the same one returns the existing account rather than creating a second.

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.

Requires the manage_accounts entitlement.

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: the member's other grants are left exactly as they were. NONE is not accepted here — remove access by deleting the grant. OWNER and ADMIN members reach every company implicitly and cannot receive grants.

Endpoint: PUT /v1/accounts/{account_id}/members/{member_id}/grants/{company_id}

Makes the member in the body the account's OWNER and steps the calling owner down to ADMIN, so the account always keeps exactly one owner. It states the desired owner rather than performing a transfer, so repeating the same call once that member already owns the account returns the same 204 instead of failing.

Unlike the rest of this API, this operation is available only from a signed-in dashboard session: no API key, live or test, can perform it, whatever scopes it holds. To hand an account over to its holder from an integration, issue a claim token with POST /v1/accounts/{account_id}/claim-tokens instead.

Endpoint: PUT /v1/accounts/{account_id}/owner

Re-sends the original payload of a delivery immediately and records the outcome as a new entry in the delivery history; the original entry is kept as it was. The payload is the one captured when the event happened, not a fresh snapshot, so changes made to the entity since then are not reflected.

Endpoint: POST /v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/retry

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.

Only events whose retry_available is true can be retried: the status and the skip reason must admit reprocessing and the event must still be under the limit of 3 retries (retry_count). Anything else returns 400. Read retry_available instead of deriving retryability from status yourself.

Endpoint: POST /v1/companies/{company_id}/payment-connections/{provider}/events/{event_id}/retry

Generates a new HMAC secret for a webhook subscription. The old secret is immediately invalidated — update your signature verification logic before rotating to avoid missing events during the transition. The new secret is only returned once in this response.

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 (NIF), and unmarks the previous one. Only one series can be the default per company and document type, and the series must be active — an inactive one is rejected with 400. 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. On scheduled_for, which must be today or later, generation_mode: DRAFT leaves the invoice as a draft for manual review and ISSUE_AND_SEND issues and sends it automatically. Both fields are required.

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: PAID from ISSUED, SENT or OVERDUE, SENT from ISSUED, and ISSUED from SENT only, to undo a SENT set by mistake. Any other transition is rejected.

Issuing and voiding are not statuses set here: they are fiscal acts with their own operations, 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, which 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 is reached on its own when the schedule runs out and cannot be set through this operation. Transitions that the schedule does not allow — resuming a template that is already active, or one paused because the company still cannot issue — are rejected.

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.

The payload carries "test": true and synthetic data, and is signed like any other delivery, so it also verifies your signature check. It is not retried on failure and does not appear in the delivery history.

Repeating the call with the same Idempotency-Key returns the cached result without sending the test payload again.

Endpoint: POST /v1/accounts/{account_id}/webhooks/{webhook_id}/test

Updates how the invoices of a company (NIF) 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

Replaces the tax configuration of a company (NIF): default tax regime, main percentage and regime key, IRPF and equivalence surcharge.

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. Applying the surcharge without regime key 18 answers 422 RECARGO_REQUIRES_REGIME_RE.

Endpoint: PUT /v1/companies/{company_id}/tax-configuration

Replaces the VeriFactu configuration of a company (NIF). Only enabled and apply_by_default are writable and both are required — this is a full replacement, not a partial merge; the rest of the returned configuration is resolved server-side. apply_by_default cannot be true while enabled is false, which answers 422 APPLY_BY_DEFAULT_REQUIRES_ENABLED.

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.

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

Checks a NIF or CIF against the AEAT register through VeriFactu and returns what the register says about it. 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.

What valid: true means depends on the kind of 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 valid: true says nothing about your name. legal_name_verified tells the two cases apart, and census_status says whether an identified NIF is also deregistered or revoked.

A NIF with 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. What is an error is sending no NIF at all — an absent or empty nif answers 422 FIELD_BLANK, with details.field naming it. This operation only reads the register: it creates nothing and stores no customer.

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 VeriFactu is enabled a cancellation record is submitted to AEAT. Use it when the operation never took place; if it did take place but with errors, issue a corrective invoice instead.

Voiding an ACTIVE proforma is a direct status change with no fiscal effect: it creates no corrective invoice and nothing is submitted to 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.

Search the BeeL API documentation (VeriFactu, invoice types, taxes, regime keys, corrective invoices, international customers, worked examples). Returns the most relevant sections. Use this before building non-trivial invoices or when unsure about a fiscal rule.

Fetch a full documentation page by title (all its sections), e.g. "Invoice types" or "Regime keys". Use after beel_docs_list or beel_docs_search to read a page in full.

List the available BeeL documentation pages (titles and URLs).

Read-only setup status across your account: for each NIF (company) it reports whether it can issue Live, exactly what is missing (issuing-readiness blockers, default series, VeriFactu, payment connection) and the single recommended next action. Use this to drive onboarding instead of guessing. Aggregates several endpoints; degrades gracefully on partial failures.