NewStripe: a buyer with a NIF always gets a standard invoice, and the simplified threshold is deprecated
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
VeriFactu Configuration

Update the VeriFactu configuration of a company

Scopeconfiguration:write

Replaces the VeriFactu configuration of a company.

  • Writable fields: only enabled, and it is required — this is a full replacement, not a partial merge. The rest of the returned configuration is resolved server-side.
  • Turning it on registers the NIF for VeriFactu submission in the same call, atomically: if the registration is refused nothing is persisted and the response carries the reason. In Live it requires a signed and validated AEAT representation first, or 422 VERIFACTU_REPRESENTATION_REQUIRED.
  • Sandbox is always on: enabled: false there answers 422 VERIFACTU_ALWAYS_ON_IN_SANDBOX.

Turning it off

Setting enabled to false stops sending this company's invoices to AEAT and starts deregistering the NIF from VeriFactu submission. 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.

PUT
/v1/companies/{company_id}/verifactu-configuration

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Path Parameters

company_idstring

Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.

Formatuuid

Request Body

enabledboolean

Whether this tax ID is under the VeriFactu regime in the environment of the request.

It is a fact about the taxpayer, not about a document: while it is on, every invoice of this tax ID is registered with the AEAT; while it is off, none is. There is no per-invoice choice.

Turning it on registers the tax ID for VeriFactu submission in the same call, atomically: if the registration is refused, nothing is persisted and the response carries the reason. In Live it requires a signed and validated AEAT representation first (VERIFACTU_REPRESENTATION_REQUIRED).

In sandbox VeriFactu is always on and cannot be turned off (VERIFACTU_ALWAYS_ON_IN_SANDBOX): nothing there reaches the real AEAT.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/verifactu-configuration" \  -H "Content-Type: application/json" \  -d '{    "enabled": true  }'
{
  "success": true,
  "data": {
    "enabled": true,
    "nif_status": "ACTIVATED",
    "nif_registered_at": "2019-08-24T14:15:22Z",
    "status": "DISABLED",
    "signed": true,
    "activated": true,
    "pdf_generated": true
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  },
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "The invoice must have at least one line",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  },
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "The invoice must have at least one line",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid.",
    "details": {
      "legal_name": "The field 'legal_name' cannot be empty",
      "recipient.address.postal_code": "Contains invalid characters."
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Get the VeriFactu configuration of a company GET

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

Get VeriFactu configuration (deprecated) GET

**Deprecated.** Use `GET /v1/companies/{company_id}/verifactu-configuration`, which behaves identically. Returns the VeriFactu configuration in force for the company in focus. - **Writable state:** `enabled` says whether this tax ID is under the VeriFactu regime in this environment: while it is on, every invoice of the NIF is registered with the AEAT. - **Resolved state:** `status`, `signed`, `activated` and `nif_status` are read-only and resolved server-side. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.