Activate a compliance system for a company
Scopeconfiguration:writeActivates 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_fromtoday applies the system from now on; a later date schedules it. A date in the past answers422 COMPLIANCE_EFFECTIVE_DATE_IN_PAST. - Changing the settings: activating a system that already applies, with other
settings, ends its current period oneffective_fromand 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
200and 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 answers422 COMPLIANCE_SYSTEMS_INCOMPATIBLEand nothing changes. - VeriFactu: activating
VERIFACTUbehaves like turning VeriFactu on withPUT /v1/companies/{company_id}/verifactu-configuration, with the same errors. That resource stays available and reports the same state. VeriFactu has nosettings. 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 wheneffective_fromis a later date. - SII:
settings.periodicityandsettings.reasonare required, andacknowledge_responsibilitymust betrue. 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 byeffective_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
VERIFACTUwhile the SII applies) and changingsettings.reasonorsettings.periodicity. Leaving the SII never takes effect on a past date. The company enters the SII on 1 January, unless it declares withsettings.already_in_siithat 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 whensettings.reasonisVOLUNTARYorMANDATORY_LARGE_COMPANY, from the first day of a month when it isREDEME, and on any date when it isVAT_GROUP. Changingsettings.periodicityof the SII in force takes effect on 1 January, so it is scheduled before that day. Moving fromVOLUNTARYto anotherreasonkeeps the company in the SII and is accepted on any date from tomorrow. Any other change ofsettings.reasonends the period in force, so it follows the rule for leaving under thereasonof 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:
- The request:
VALIDATION_ERROR,IDEMPOTENCY_KEY_REQUIRED. - Access to the company:
403. - A body equal to the activation in force or to the scheduled one:
200, no change. - The system in the environment:
COMPLIANCE_SYSTEM_NOT_AVAILABLE; withSIIin Live,SII_NOT_CONTRACTEDand then402. - The SII settings:
SII_ACKNOWLEDGEMENT_REQUIRED,SII_QUARTERLY_REQUIRES_VOLUNTARY,SII_TERRITORY_NOT_SUPPORTED. - 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. - With
VERIFACTUin Live:VERIFACTU_REPRESENTATION_REQUIRED. - 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.
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
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.
uuidThe compliance system the operation acts on. A value that is not listed answers
400 VALIDATION_ERROR.
"VERIFACTU" | "SII"Header Parameters
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.
^[a-zA-Z0-9_-]+$length <= 255First 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.
dateThe 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.
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.
Response Body
application/json
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/activate" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "effective_from": "2027-01-01", "settings": { "periodicity": "MONTHLY", "reason": "MANDATORY_LARGE_COMPANY" }, "acknowledge_responsibility": true }'{
"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"
}
}{
"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": "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"
}
}{
"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_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"
}
}{
"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"
}
}List the invoice PDF templates GET
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. **Closed catalogue.** This collection is fixed and bounded: it carries no `pagination`, it takes no `page`/`limit`, and every response holds the whole set.
Deactivate a compliance system of a company POST
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`.