# Activate a compliance system for a company API Reference

Activates `system` for this company from `effective_from` on, in the environment of the
request, with the `settings` of that system. It is a fact of the taxpayer: it applies to
every invoice issued from that date, never to a single one.

- **Today or later:** `effective_from` today applies the system from now on; a later date
  schedules it. A date in the past answers `422 COMPLIANCE_EFFECTIVE_DATE_IN_PAST`.
- **Changing the settings:** activating a system that already applies, with other
  `settings`, ends its current period on `effective_from` and starts a new one. A later
  date replaces an activation of the same system that is still scheduled.
- **Same body, no change:** a body equal to the activation in force or to the scheduled
  one answers `200` and changes nothing.
- **Systems that exclude each other:** VeriFactu and the SII never apply on the same day.
  Activating one ends the other on `effective_from`, in the same call, and the response
  shows how the company is left. When that is not possible, the request answers
  `422 COMPLIANCE_SYSTEMS_INCOMPATIBLE` and nothing changes.
- **VeriFactu:** activating `VERIFACTU` behaves like turning VeriFactu on with
  `PUT /v1/companies/{company_id}/verifactu-configuration`, with the same errors. That
  resource stays available and reports the same state. VeriFactu has no `settings`.
  In Live, the signed and validated AEAT representation is required and the NIF is
  registered for VeriFactu submission at the time of the call, also when
  `effective_from` is a later date.
- **SII:** `settings.periodicity` and `settings.reason` are required, and
  `acknowledge_responsibility` must be `true`. Activating it registers the NIF of the
  company for SII submission, so it needs a NIF, as VeriFactu does. The option for the
  SII must be in force in the AEAT tax census by `effective_from`: otherwise the AEAT
  rejects the submissions.
- **SII in Live:** the account needs the SII contracted, and every change of the SII
  takes effect tomorrow at the earliest: entering it, leaving it (also by activating
  `VERIFACTU` while the SII applies) and changing `settings.reason` or
  `settings.periodicity`. Leaving the SII never takes effect on a past date. The company
  enters the SII on 1 January, unless it declares with `settings.already_in_sii` that it
  is already in the SII: then it can enter on any date. Once in the SII, it can only be
  left from 1 January when `settings.reason` is `VOLUNTARY` or
  `MANDATORY_LARGE_COMPANY`, from the first day of a month when it is `REDEME`, and on
  any date when it is `VAT_GROUP`.
  Changing `settings.periodicity` of the SII in force takes effect on 1 January, so it is
  scheduled before that day. Moving from `VOLUNTARY` to another `reason` keeps the
  company in the SII and is accepted on any date from tomorrow. Any other change of
  `settings.reason` ends the period in force, so it follows the rule for leaving under
  the `reason` of that period.
- **SII in Sandbox:** no contract is needed, and the company can enter and leave the SII
  and change its settings on any date from today.

## Order of the rules

The rules are checked in this order, and the first one that fails answers; nothing is
changed:

1. The request: `VALIDATION_ERROR`, `IDEMPOTENCY_KEY_REQUIRED`.
2. Access to the company: `403`.
3. A body equal to the activation in force or to the scheduled one: `200`, no change.
4. The system in the environment: `COMPLIANCE_SYSTEM_NOT_AVAILABLE`; with `SII` in Live,
   `SII_NOT_CONTRACTED` and then `402`.
5. The SII settings: `SII_ACKNOWLEDGEMENT_REQUIRED`, `SII_QUARTERLY_REQUIRES_VOLUNTARY`,
   `SII_TERRITORY_NOT_SUPPORTED`.
6. The dates: `COMPLIANCE_EFFECTIVE_DATE_IN_PAST`, `SII_CHANGE_ONLY_FROM_TOMORROW`,
   `SII_ENTRY_ONLY_FROM_JANUARY_FIRST`, `SII_EXIT_ONLY_FROM_JANUARY_FIRST`,
   `SII_EXIT_ONLY_FROM_MONTH_START`, `SII_PERIODICITY_CHANGE_ONLY_FROM_JANUARY_FIRST`,
   `COMPLIANCE_SYSTEMS_INCOMPATIBLE`.
7. With `VERIFACTU` in Live: `VERIFACTU_REPRESENTATION_REQUIRED`.
8. The registration of the NIF: `COMPANY_NIF_MISSING`, `API_COMMUNICATION_ERROR`.

`PUT /v1/companies/{company_id}/verifactu-configuration` with `enabled: true` is this
operation with `VERIFACTU` and `effective_from` today, in the same order.

The response carries the same body as `GET /v1/companies/{company_id}/compliance`.


## POST /v1/companies/{company_id}/compliance/systems/{system}/activate

**Activate a compliance system for a company**

Activates `system` for this company from `effective_from` on, in the environment of the
request, with the `settings` of that system. It is a fact of the taxpayer: it applies to
every invoice issued from that date, never to a single one.

- **Today or later:** `effective_from` today applies the system from now on; a later date
  schedules it. A date in the past answers `422 COMPLIANCE_EFFECTIVE_DATE_IN_PAST`.
- **Changing the settings:** activating a system that already applies, with other
  `settings`, ends its current period on `effective_from` and starts a new one. A later
  date replaces an activation of the same system that is still scheduled.
- **Same body, no change:** a body equal to the activation in force or to the scheduled
  one answers `200` and changes nothing.
- **Systems that exclude each other:** VeriFactu and the SII never apply on the same day.
  Activating one ends the other on `effective_from`, in the same call, and the response
  shows how the company is left. When that is not possible, the request answers
  `422 COMPLIANCE_SYSTEMS_INCOMPATIBLE` and nothing changes.
- **VeriFactu:** activating `VERIFACTU` behaves like turning VeriFactu on with
  `PUT /v1/companies/{company_id}/verifactu-configuration`, with the same errors. That
  resource stays available and reports the same state. VeriFactu has no `settings`.
  In Live, the signed and validated AEAT representation is required and the NIF is
  registered for VeriFactu submission at the time of the call, also when
  `effective_from` is a later date.
- **SII:** `settings.periodicity` and `settings.reason` are required, and
  `acknowledge_responsibility` must be `true`. Activating it registers the NIF of the
  company for SII submission, so it needs a NIF, as VeriFactu does. The option for the
  SII must be in force in the AEAT tax census by `effective_from`: otherwise the AEAT
  rejects the submissions.
- **SII in Live:** the account needs the SII contracted, and every change of the SII
  takes effect tomorrow at the earliest: entering it, leaving it (also by activating
  `VERIFACTU` while the SII applies) and changing `settings.reason` or
  `settings.periodicity`. Leaving the SII never takes effect on a past date. The company
  enters the SII on 1 January, unless it declares with `settings.already_in_sii` that it
  is already in the SII: then it can enter on any date. Once in the SII, it can only be
  left from 1 January when `settings.reason` is `VOLUNTARY` or
  `MANDATORY_LARGE_COMPANY`, from the first day of a month when it is `REDEME`, and on
  any date when it is `VAT_GROUP`.
  Changing `settings.periodicity` of the SII in force takes effect on 1 January, so it is
  scheduled before that day. Moving from `VOLUNTARY` to another `reason` keeps the
  company in the SII and is accepted on any date from tomorrow. Any other change of
  `settings.reason` ends the period in force, so it follows the rule for leaving under
  the `reason` of that period.
- **SII in Sandbox:** no contract is needed, and the company can enter and leave the SII
  and change its settings on any date from today.

## Order of the rules

The rules are checked in this order, and the first one that fails answers; nothing is
changed:

1. The request: `VALIDATION_ERROR`, `IDEMPOTENCY_KEY_REQUIRED`.
2. Access to the company: `403`.
3. A body equal to the activation in force or to the scheduled one: `200`, no change.
4. The system in the environment: `COMPLIANCE_SYSTEM_NOT_AVAILABLE`; with `SII` in Live,
   `SII_NOT_CONTRACTED` and then `402`.
5. The SII settings: `SII_ACKNOWLEDGEMENT_REQUIRED`, `SII_QUARTERLY_REQUIRES_VOLUNTARY`,
   `SII_TERRITORY_NOT_SUPPORTED`.
6. The dates: `COMPLIANCE_EFFECTIVE_DATE_IN_PAST`, `SII_CHANGE_ONLY_FROM_TOMORROW`,
   `SII_ENTRY_ONLY_FROM_JANUARY_FIRST`, `SII_EXIT_ONLY_FROM_JANUARY_FIRST`,
   `SII_EXIT_ONLY_FROM_MONTH_START`, `SII_PERIODICITY_CHANGE_ONLY_FROM_JANUARY_FIRST`,
   `COMPLIANCE_SYSTEMS_INCOMPATIBLE`.
7. With `VERIFACTU` in Live: `VERIFACTU_REPRESENTATION_REQUIRED`.
8. The registration of the NIF: `COMPANY_NIF_MISSING`, `API_COMMUNICATION_ERROR`.

`PUT /v1/companies/{company_id}/verifactu-configuration` with `enabled: true` is this
operation with `VERIFACTU` and `effective_from` today, in the same order.

The response carries the same body as `GET /v1/companies/{company_id}/compliance`.

### Authentication

Accepts any of:

- `ApiKeyAuth` (HTTP bearer, token format `beel_sk_*`)

### Parameters

- **company_id** (required) in path `string`: 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.
- **system** (required) in path: The compliance system the operation acts on. A value that is not listed answers `400 VALIDATION_ERROR`.
- **Idempotency-Key** (required) in header `string`: Same key and rules as `Idempotency-Key` above, but **required**: the operation has an effect that must never happen twice, such as importing the same file again or applying the same change of regime twice, so a retry is only safe with a key. A missing key answers `400 IDEMPOTENCY_KEY_REQUIRED`.

### Request Body

Required.

**Content `application/json`:**

- **effective_from** (required) `string` (date): First day the system applies, as a date in Spain: today, so that it applies from now on, or a later date, so that it is scheduled. A date in the past answers `422 COMPLIANCE_EFFECTIVE_DATE_IN_PAST`. (example: "2027-01-01")
- **settings** `ComplianceSystemSettings`: The settings of one compliance system. Each property belongs to the system its description names, and only that system accepts or returns it; a system without settings, such as `VERIFACTU`, returns `{}`. Properties are added as systems are added: ignore one you do not know.
- **acknowledge_responsibility** `boolean`: Required as `true` to activate the SII: the company confirms that it is subject to the SII for the `reason` given and that the data it reports is its responsibility. With `settings.already_in_sii`, it also confirms that the records of the calendar year before `effective_from` are submitted by the company or its previous provider. Leaving it out, or sending `false`, answers `422 SII_ACKNOWLEDGEMENT_REQUIRED`. Ignored with any other system.

**Example `sii`** — Report through the SII from 1 January:

```json
{
  "effective_from": "2027-01-01",
  "settings": {
    "periodicity": "MONTHLY",
    "reason": "MANDATORY_LARGE_COMPANY"
  },
  "acknowledge_responsibility": true
}
```

**Example `verifactu`** — Register with VeriFactu from today:

```json
{
  "effective_from": "2026-11-12"
}
```

### Responses

#### 200: System activated, or already activated with the same body

**Content `application/json`:**

- **success** (required) `boolean`: No description (example: true)
- **data** (required): The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1.
- **meta** `ResponseMeta`
- **data** `CompanyCompliance`: The compliance systems of a company in the environment of the request: the ones that apply today and the ones scheduled to start later. Periods that have ended are not listed.

**Example `sii_scheduled`** — VeriFactu today, SII scheduled from 1 January:

```json
{
  "success": true,
  "data": {
    "systems": [
      {
        "system": "VERIFACTU",
        "status": "ACTIVE",
        "effective_from": "2026-03-02",
        "effective_to": "2027-01-01",
        "settings": {},
        "created_at": "2026-03-02T09:30:00Z",
        "created_by": "6f1e2d3c-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
      },
      {
        "system": "SII",
        "status": "SCHEDULED",
        "effective_from": "2027-01-01",
        "effective_to": null,
        "settings": {
          "periodicity": "MONTHLY",
          "reason": "MANDATORY_LARGE_COMPANY",
          "already_in_sii": false
        },
        "created_at": "2026-11-12T10:15:00Z",
        "created_by": "6f1e2d3c-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-11-12T10:15:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 400: The request could not be processed. Branch on `error.code`:

* `VALIDATION_ERROR`: `system` in the path is not a system that can be activated;
  `error.details` names it.
* `IDEMPOTENCY_KEY_REQUIRED`: the `Idempotency-Key` header is missing.
* `COMPANY_NIF_MISSING`: the company has no NIF to register for submission.
* `API_COMMUNICATION_ERROR`: the registration of the NIF for submission was refused
  or could not be completed. `error.message` carries the reason when there is one;
  repeat the request once it is fixed or later.

The NIF is registered at the time of the call, also when `effective_from` is a later
date. A body that cannot be parsed is also answered with `400`. Nothing was changed.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

#### 401: Missing or invalid authentication. `error.code` is `UNAUTHORIZED`, except for an access
token of BeeL's automations client whose authorization has been revoked (the user revoked
the connection, or was removed from the account it was granted for): then it is
`OAUTH_AUTHORIZATION_REVOKED`. Any other OAuth token answers `UNAUTHORIZED`.
Refreshing the token will not help; the user has to connect again. Like every other error,
`message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults
to English when the header is missing or asks for none of those.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 402: Only with `system` `SII` in Live: reporting through the SII in Live requires payment.
Nothing was changed and no checkout is opened. Branch on `error.code`:

* `CHECKOUT_REQUIRED`: the account has no card on file. Nothing is owed; billing has
  not been set up yet.
* `PAYMENT_REQUIRED`: the account has billing but is unpaid, because payment retries
  are exhausted. The outstanding invoice has to be settled first. A failed charge that
  is still being retried does not block Live.
* `PLAN_ACTIVATION_REQUIRED`: the account is on a fixed-quota plan still on trial;
  activating the plan unblocks Live.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

#### 403: Your account does not own or manage this company, or does not hold the required
access over it. A company that does not exist answers the same way, with `error.code`
`ACTIVE_COMPANY_NOT_ACCESSIBLE`.

`SII_NOT_CONTRACTED`: `system` is `SII`, the request is in Live and the account has
not contracted the SII. Contact BeeL. to enable it. In Sandbox the SII needs no
contract. Nothing was changed.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example `sii_not_contracted`**:

```json
{
  "success": false,
  "error": {
    "code": "SII_NOT_CONTRACTED",
    "message": "The SII is not contracted for this account. Contact BeeL. to enable it."
  },
  "meta": {
    "timestamp": "2026-11-12T10:15:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 409: `IDEMPOTENCY_KEY_PROCESSING` or `IDEMPOTENCY_KEY_MISMATCH`, as described for the
`Idempotency-Key` header. Nothing was changed.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

#### 422: The body parses but the change cannot be made. Nothing was changed. Branch on
`error.code`:

* `VALIDATION_ERROR`: a field fails validation, including a required setting missing
  or a setting of another system sent; `error.details` names the field.
* `COMPLIANCE_EFFECTIVE_DATE_IN_PAST`: `effective_from` is before today, by the date
  in Spain.
* `SII_CHANGE_ONLY_FROM_TOMORROW`: in Live, the request enters the SII, activates
  `VERIFACTU` while the SII applies, or changes `settings.reason` or
  `settings.periodicity` of the SII in force, with `effective_from` today. Use
  tomorrow or a later date.
* `COMPLIANCE_SYSTEMS_INCOMPATIBLE`: the other system (VeriFactu or the SII) cannot be
  ended on `effective_from`, for example because it is scheduled to start later.
  Deactivate it with
  `POST /v1/companies/{company_id}/compliance/systems/{system}/deactivate` and retry.
* `COMPLIANCE_SYSTEM_NOT_AVAILABLE`: the system cannot be activated in the
  environment of the request.
* `SII_ACKNOWLEDGEMENT_REQUIRED`: `system` is `SII` and `acknowledge_responsibility`
  is not `true`.
* `SII_TERRITORY_NOT_SUPPORTED`: `system` is `SII` and the fiscal address of the
  company (its postal code) is outside the territory where the AEAT manages VAT: the
  Basque Country, Navarre, the Canary Islands, Ceuta or Melilla, or outside Spain. A
  company with its fiscal address in the Basque Country or Navarre that reports
  through the SII of the AEAT because of its volume of operations is not supported
  yet.
* `SII_QUARTERLY_REQUIRES_VOLUNTARY`: `settings.periodicity` is `QUARTERLY` and
  `settings.reason` is not `VOLUNTARY`.
* `SII_ENTRY_ONLY_FROM_JANUARY_FIRST`: in Live, `system` is `SII`, the SII does not
  apply to the company the day before `effective_from`, `effective_from` is not
  1 January, and either `settings.already_in_sii` is not `true` or the company has
  already issued invoices in Live through VeriFactu that calendar year.
* `SII_EXIT_ONLY_FROM_JANUARY_FIRST`: in Live, the request would end the SII in force
  on a date other than 1 January, and its `settings.reason` is `VOLUNTARY` or
  `MANDATORY_LARGE_COMPANY`. This happens when activating `VERIFACTU` or changing
  `settings.reason`, except when moving from `VOLUNTARY`, which keeps the company in
  the SII.
* `SII_EXIT_ONLY_FROM_MONTH_START`: in Live, the SII in force has `settings.reason`
  `REDEME`, and activating `VERIFACTU` or changing `settings.reason` would end it on a
  date other than the first day of a month.
* `SII_PERIODICITY_CHANGE_ONLY_FROM_JANUARY_FIRST`: in Live, `system` is `SII`, the SII
  applies, the request changes `settings.periodicity` but not `settings.reason`, and
  `effective_from` is not 1 January. A change for 1 January is scheduled before that
  day.
* `VERIFACTU_REPRESENTATION_REQUIRED`: with `VERIFACTU` in Live, the company has no
  signed and validated AEAT representation yet.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example `effective_date_in_past`**:

```json
{
  "success": false,
  "error": {
    "code": "COMPLIANCE_EFFECTIVE_DATE_IN_PAST",
    "message": "The date cannot be earlier than today. Use today or a later date."
  },
  "meta": {
    "timestamp": "2026-11-12T10:15:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

**Example `acknowledgement_required`**:

```json
{
  "success": false,
  "error": {
    "code": "SII_ACKNOWLEDGEMENT_REQUIRED",
    "message": "To report through the SII, confirm that you are responsible for it."
  },
  "meta": {
    "timestamp": "2026-11-12T10:15:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 429: Rate limit exceeded. `RATE_LIMIT_EXCEEDED` when the request rate of your credential is
over its limit; `TOO_MANY_REQUESTS` when an email the operation sends is held back because
too many went out to that recipient in a short time. Either way, retry after the
`Retry-After` seconds.

`QUOTA_EXCEEDED` is the other `429`: the operation would go over a quota of your plan
for the current period (issued invoices, for instance). Retrying does not help until the
quota resets or the plan changes. `error.details` carries `feature_code`,
`current_usage`, `quota_limit` and `reset_date`, and `RateLimit-Reset` the seconds until
the reset when it is known.


**Headers:**

- `Retry-After` `integer`: Seconds until the rate limit resets
- `RateLimit-Limit` `integer`: Maximum requests allowed in the window
- `RateLimit-Remaining` `integer`: Remaining requests in the current window
- `RateLimit-Reset` `integer`: Seconds until the current window resets

**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "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"
  }
}
```

#### 500: Internal server error

**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### default: Any status code the operation does not list above. Every operation declares it, so a
generated client always has a branch to fall into and never loses the cause of a failure
it did not anticipate.

This is where the transport-level answers land — `405`, `406`, `415` and `429` — together
with any status a future version of the API starts returning. All of them carry the same
error envelope as the codes listed explicitly, so `error.code` is what tells them apart:
switching on the status code alone is not enough. See «Transport-level errors» in the
API description for when each one is produced.

A `402` carrying `SUBSCRIPTION_REQUIRED` lands here when the account has no active
subscription. `error.details` says why and what to do: `current_status` (absent if it
never had one), `required_permission` and `action`.

A `503` carrying `SERVICE_UNAVAILABLE` lands here too, with a `Retry-After` header: a
dependency of BeeL itself (the database, the email provider) was momentarily
unavailable and nothing was done. Retry after those seconds.

A `502` carrying `EXTERNAL_SERVICE_ERROR` also lands here: an outbound integration the
operation depends on failed or did not answer in time. It is a transient condition — retry
with the same `Idempotency-Key` where the operation accepts one.

One exception to the envelope: a failure of the network edge that never reaches the
application (`502`, `503`, `504`, `524`) is generated by Cloudflare and its body is not
BeeL's — it may not even be JSON. Treat those as "no answer", and retry.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "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"
  }
}
```

---

# Related Schema Definitions

## ActivateComplianceSystemRequest

Request body of `POST /v1/companies/{company_id}/compliance/systems/{system}/activate`:
the system applies from `effective_from` on, with these `settings`.

- **effective_from** (required) `string` (date): First day the system applies, as a date in Spain: today, so that it applies from now on, or a later date, so that it is scheduled. A date in the past answers `422 COMPLIANCE_EFFECTIVE_DATE_IN_PAST`. (example: "2027-01-01")
- **settings** `ComplianceSystemSettings`: The settings of one compliance system. Each property belongs to the system its description names, and only that system accepts or returns it; a system without settings, such as `VERIFACTU`, returns `{}`. Properties are added as systems are added: ignore one you do not know.
- **acknowledge_responsibility** `boolean`: Required as `true` to activate the SII: the company confirms that it is subject to the SII for the `reason` given and that the data it reports is its responsibility. With `settings.already_in_sii`, it also confirms that the records of the calendar year before `effective_from` are submitted by the company or its previous provider. Leaving it out, or sending `false`, answers `422 SII_ACKNOWLEDGEMENT_REQUIRED`. Ignored with any other system.

## ComplianceSystemSettings

The settings of one compliance system. Each property belongs to the system its
description names, and only that system accepts or returns it; a system without
settings, such as `VERIFACTU`, returns `{}`. Properties are added as systems are
added: ignore one you do not know.

- **periodicity**: `SII` only, and required to activate it. `QUARTERLY` requires `reason` `VOLUNTARY`, or `422 SII_QUARTERLY_REQUIRES_VOLUNTARY`.
- **reason**: `SII` only, and required to activate it.
- **already_in_sii** `boolean`: `SII` only; absent means `false`. `true` declares that the company is already registered for the SII in the AEAT tax census, and that the records of the calendar year up to `effective_from`, from 1 January on, are submitted by the company itself or by its previous provider: BeeL. does not report them. It lets the company enter the SII in Live on a date other than 1 January. Without it, that date answers `422 SII_ENTRY_ONLY_FROM_JANUARY_FIRST`, and so does a company that has already issued invoices in Live through VeriFactu that calendar year. The period returns the value it was activated with.

## SuccessResponse

The envelope every successful JSON response of the BeeL. API is wrapped in. There are no
bare resources in v1 and none are planned: the payload always hangs off `data`.

- A **single resource** is an object in `data`.
- A **collection** hangs off a named key inside `data`, together with its `pagination`,
  also inside `data` — `data: {invoices: [...], pagination: {...}}`.
- A collection carries `pagination` unless its operation declares itself a **closed
  catalogue**: a fixed, bounded list with nothing to page through. The declaration is
  explicit in the operation; a missing `pagination` is never something to infer.
- `GET /v1/accounts` pages by cursor (`data: {accounts: [...], next_cursor}`). It is a
  documented variant of pagination, not another envelope.

Putting the array straight into `data` with `pagination` as its sibling is the shape a v2
would adopt; v1 is not being flipped to it.

- **success** (required) `boolean`: No description (example: true)
- **data** (required): The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1.
- **meta** `ResponseMeta`

## ResponseMeta

- **timestamp** `string` (date-time): No description (example: "2025-01-15T10:30:00Z")
- **request_id** `string`: No description (example: "4bf92f3577b34da6a3ce929d0e0e4736")

## CompanyCompliance

The compliance systems of a company in the environment of the request: the ones that
apply today and the ones scheduled to start later. Periods that have ended are not
listed.

- **systems** (required) `array[CompanyComplianceSystem]`: One entry per period, ordered by `effective_from`. Empty when no system applies or is scheduled: BeeL. does not report the invoices of the company to the AEAT.

## ErrorResponse

Error response shared by all BeeL. APIs.

The payload carries **two contracts at once** (additive, non-breaking):

- **Legacy** (`success`, `error.{code,message,details}`, `meta`) — kept
  intact for existing consumers.
- **RFC 9457** (`type`, `title`, `detail`, `instance`) — new fields
  for integrators following Problem Details for HTTP APIs. The
  `type` URI is the stable, shareable link to the error's
  documentation page (e.g. `https://docs.beel.es/errors/{code}`).

Future migration: the legacy fields will be deprecated via
`Deprecation`/`Sunset` headers after a sufficient adoption window,
and the response Content-Type will move to
`application/problem+json`.

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

## ErrorDetail

- **code** (required) `string`: No description (example: "VALIDATION_ERROR")
- **message** (required) `string`: No description (example: "The provided data is not valid")
- **details** `object`: No description (example: {"field":"specific error message"})

## CompanyComplianceSystem

One period during which a compliance system applies to a company, in the environment of
the request.

- **system** (required) `ComplianceSystem`: A tax system the AEAT requires invoices to be reported through. It is used both for the systems an invoice is owed to and for the systems a company reports through. * `VERIFACTU`: registration with the AEAT under VeriFactu. * `SII`: the AEAT ledger of issued invoices (Immediate Supply of Information). Available under contract. More systems will be added: ignore an invoice entry or a company period whose system you do not know.
- **status** (required) `CompanyComplianceSystemStatus`: * `ACTIVE`: the system applies today. * `SCHEDULED`: the system starts applying on `effective_from`, a later date.
- **effective_from** (required) `string` (date): First day the system applies, as a date in Spain. Invoices whose issue date falls on or after it are reported through it. (example: "2027-01-01")
- **effective_to** (required) `string` (date): First day the system no longer applies, as a date in Spain, or null when no end is set. Activating a system that excludes this one, or deactivating this one, sets it. (example: null)
- **settings** (required) `ComplianceSystemSettings`: The settings of one compliance system. Each property belongs to the system its description names, and only that system accepts or returns it; a system without settings, such as `VERIFACTU`, returns `{}`. Properties are added as systems are added: ignore one you do not know.
- **created_at** (required) `string` (date-time): When this period was set. Null for one BeeL. set on its own, such as the system a company starts with. (example: "2026-11-12T10:15:00Z")
- **created_by** (required) `string` (uuid): The person who set this period, as the `person_id` of an account member. Null when no person can be attributed. (example: "6f1e2d3c-4b5a-4c7d-8e9f-0a1b2c3d4e5f")

## ComplianceSystem

A tax system the AEAT requires invoices to be reported through. It is used both for the
systems an invoice is owed to and for the systems a company reports through.

* `VERIFACTU`: registration with the AEAT under VeriFactu.
* `SII`: the AEAT ledger of issued invoices (Immediate Supply of Information). Available
  under contract.

More systems will be added: ignore an invoice entry or a company period whose system you
do not know.

Type: `string`

## CompanyComplianceSystemStatus

* `ACTIVE`: the system applies today.
* `SCHEDULED`: the system starts applying on `effective_from`, a later date.

Type: `string` — one of: ACTIVE, SCHEDULED


---

Full OpenAPI spec: https://docs.beel.es/api/openapi