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

Activate a compliance system for a company

Scopeconfiguration:write

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
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_fromstring

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.

Formatdate
settings?

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.

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