NewThe SII in Live, under contract
BeeL
Get startedMulti-NIFVeriFactuSIIRulesStripeAPI referenceChangelog
Compliance

Deactivate a compliance system of a company

Scopeconfiguration:write

Stops system from applying to this company from effective_to on, in the environment of the request, without activating another one in its place. Invoices issued on or after that date are not reported through it. To move to a system that excludes this one, activate that one instead: the switch happens in a single call.

  • Today or later: without effective_to (send {}), the system stops applying today. A date in the past answers 422 COMPLIANCE_EFFECTIVE_DATE_IN_PAST.
  • Scheduled activations: one that would start on or after effective_to is cancelled, which is always accepted; one that is in force, or starts before, ends on effective_to, and for the SII that is leaving it.
  • Nothing to deactivate: when the system does not apply on or after effective_to, the request answers 200 and changes nothing.
  • Sandbox: a company in Sandbox always reports through VeriFactu or the SII, so deactivating the one that applies, without activating the other, answers 422 COMPLIANCE_REQUIRED_IN_SANDBOX.
  • VeriFactu: deactivating VERIFACTU behaves like turning VeriFactu off with PUT /v1/companies/{company_id}/verifactu-configuration, with the same effects.
  • SII in Live: leaving it takes effect tomorrow at the earliest, never on a past date. 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, judged by the reason of the period in force. This also applies to an SII activation that is scheduled and would end after it starts.
  • SII in Sandbox: it can be left on any date from today.
  • Cancelling a scheduled SII: the VeriFactu period that ended on its effective_from is left without an end date.

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


POST
/v1/companies/{company_id}/compliance/systems/{system}/deactivate
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
systemstring

The compliance system the operation acts on. A value that is not listed answers 400 VALIDATION_ERROR.

Value in"VERIFACTU" | "SII"

Header Parameters

Idempotency-Keystring

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.

Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255
effective_to?string

First day the system no longer applies, as a date in Spain: today, or a later date. Defaults to today. A date in the past answers 422 COMPLIANCE_EFFECTIVE_DATE_IN_PAST.

Formatdate

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/compliance/systems/SII/deactivate" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "effective_to": "2027-01-01"  }'
{
  "success": true,
  "data": {
    "systems": [
      {
        "system": "VERIFACTU",
        "status": "ACTIVE",
        "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": "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": {
      "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": "COMPLIANCE_REQUIRED_IN_SANDBOX",
    "message": "In Sandbox the company always reports through VeriFactu or the SII."
  },
  "meta": {
    "timestamp": "2026-11-12T10:15: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"
  }
}

Activate a compliance system for a company POST

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

Get the compliance systems of a company GET

Returns the tax systems this company reports its invoices through, in the environment of the request: the ones that apply today (`ACTIVE`) and the ones set to start on a later date (`SCHEDULED`), each with its period and its `settings`. Periods that have ended are not listed. Today is the date in Spain. The systems use the same names as the `compliance` array of an invoice, which records the ones that applied to that invoice when it was issued.