NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
VeriFactu Configuration

Update the VeriFactu configuration of a company

Scopeconfiguration:write

Replaces the VeriFactu configuration of a company (NIF).

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

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

NIF (company) the operation acts on. 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 NIF you do not reach answers 403, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed.

Formatuuid

Request Body

enabledboolean

Whether VeriFactu is enabled for this user. When enabled, the user can submit invoices to AEAT. Freelancers who don't need to submit invoices to AEAT can leave it disabled.

apply_by_defaultboolean

Whether VeriFactu should be automatically applied to new invoices. Requires 'enabled' to be true.

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,    "apply_by_default": true  }'
{
  "success": true,
  "data": {
    "enabled": false,
    "apply_by_default": false,
    "nif_status": "PENDING",
    "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": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": {
      "field_name": "Field is required"
    }
  },
  "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 (NIF). The configuration belongs to the NIF, so the NIF in the path is what decides which one is returned.

Get VeriFactu configuration GET

**Deprecated.** Use `GET /v1/companies/{company_id}/verifactu-configuration`, which behaves identically. Returns the VeriFactu configuration in force for the company (NIF) in focus. - **Writable state:** `enabled` says whether VeriFactu is on, `apply_by_default` whether it is applied by default to new invoices. - **Resolved state:** `status`, `signed`, `activated` and `nif_status` are read-only and resolved server-side.