Create a company

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

NIF/CIF of the business

Legal/fiscal name

Taxpayer type. INDIVIDUAL: Natural person (individual self-employed). LEGAL_ENTITY: Legal entity (company with legal form: SL, SA, etc.).

Address you send when you create or update a company, a customer or an onboarding.

A required field made only of whitespace passes the length checks below but leaves the address without that part, so it is rejected with 422: STREET_EMPTY, POSTAL_CODE_EMPTY, CITY_EMPTY or PROVINCE_EMPTY.

Addresses you read back are described by their own schema.

Legal form (SL, SA, ...). Recommended for LEGAL_ENTITY.

Legal representative data for a legal entity. Only used when entity_type = LEGAL_ENTITY.

Commercial/trade name (optional). When omitted or blank, the company is read back with trade_name equal to legal_name: the field always carries the name to display.

Complete tax information with cross-validations:

• IVA: real rates 4, 10, 21, and the temporary 2, 5 and 7.5 (see below for 0)
• IGIC: 0, 3, 5, 7, 9.5, 15, 20 — here 0 is the real "Tipo Cero"
• IPSI: real rates 0.5, 1, 2, 4, 8, 10 (see below for 0)
• OTHER: any percentage between 0 and 100

0 % under IVA and IPSI is not a rate, it is the exemption sentinel. It is accepted on a line, but only together with an exemption_reason (exempt or non-subject operation); on its own it says nothing and the line is rejected. That is why GET /v1/tax-types publishes the IVA rates without 0: the legitimate way to a 0 % IVA line is through an exemption reason, which the same response also publishes. IGIC is different — its 0 % is a real legal rate (basic necessities) and needs no reason.

IVA 5 % (the temporary rate applied from 2022 to electricity, gas and certain foodstuffs) is no longer in force for new operations. AEAT only accepts it on operations dated from 2022-07-01 to 2024-09-30: send the operation_date of that period, because without one the issue date decides and a line at 5 % is rejected with 422 VAT_RATE_NOT_ACCEPTED_ON_DATE. Its equivalence surcharge pair is 0.5 up to 2022-12-31 and 0.62 from 2023-01-01. IVA 2 % and 7.5 % (temporary rates of the last quarter of 2024) are accepted only on operations dated from 2024-10-01 to 2024-12-31, with surcharges 0.26 and 1.

Exception: when regime_key = "17" (OSS/IOSS) the invoice applies the destination country VAT instead of the Spanish one, so any percentage in the EU range [0, 27] is accepted regardless of the tax type set — including 0 without an exemption reason.

Default IRPF retention rate for this company's invoices. Omit it and the company is created with no withholding — BeeL never assumes a rate nobody declared.

Configuration of the invoice series the company is born with. Optional and additive: omit it — or any field — and the system default applies for that field: series F/S/R, format {CODIGO}-{YYYY}-{NUM:4}, ANNUAL counter reset, starting at 1, exactly as before.

Send it when the business already issued invoices with another system this year and wants to continue its numbering, or simply wants its series born with a specific shape — this is the only moment it can be expressed in the same call. Once a series issues its first invoice BeeL freezes its numbering: PATCH /v1/companies/{company_id}/series/{series_id} then rejects initial_number with SERIES_INITIAL_NUMBER_LOCKED_HAS_INVOICES.

It covers the three series a company is born with:

• the ordinary one (real invoices) — the fields at this level, default F.
• the simplified one (ticket-style invoices) — simplified, default S.
• the corrective one (rectificativas) — corrective, default R.

Each series takes code, initial_number, format and counter_reset, all optional and independent: omit a field and that series keeps the system default for it.

format and counter_reset must be able to tell reset periods apart, with the same rules and error codes as POST /v1/companies/{company_id}/series: a MONTHLY reset requires {MM} plus a year token in the format (SERIES_MONTHLY_REQUIRES_MONTH_AND_YEAR); an ANNUAL reset requires a year token (SERIES_ANNUAL_REQUIRES_YEAR). Mind the default reset is ANNUAL: a format without a year token (e.g. {CODIGO}-{NUM:6}) also needs counter_reset: NEVER in the same series block. Two series that could print the same number (for instance, the same literal format with no {CODIGO}) are rejected with 409 SERIES_FORMAT_OVERLAPS, because an invoice number must be unique per issuer.

The list of series is not negotiable — a company always starts with exactly these three, one default per document type, because a company without a default series cannot issue at all (NO_DEFAULT_SERIES). You configure how each of them is born, not which ones exist. More series can be added later with POST /v1/companies/{company_id}/series.

Per environment: each activation is self-contained and seeds exactly what its request carries. Activating the same NIF in the other environment later does not copy this configuration — repeat your numbering block in that activation call if you want the same series there; without it the other environment gets the system defaults.

Only valid when the request activates the company: with activate: false no series are seeded, so a numbering block that asks for anything is rejected with 422 NUMBERING_REQUIRES_ACTIVATION instead of being silently discarded.

Whether to switch the company on in aeat_environment as part of this call.

Creating a company and activating it are two different acts. The company record is free and always creatable; the activation is what seeds the invoice series, registers the NIF and — in PROD — is what gets billed.

• true (default) — unchanged behaviour: the company is created and switched on in aeat_environment, with its default series seeded there.
• false — only the company record is created. It is switched on nowhere, has no series and cannot issue yet; aeat_environment is ignored. Activate it later with POST /v1/companies/{company_id}/activations, which is also the only door that opens a Stripe Checkout when the account has no card on file.

Series numbering travels with the activation that seeds it: a request with activate: false and a numbering block that asks for anything is rejected with 422 NUMBERING_REQUIRES_ACTIVATION — the later activation door does not accept numbering, so silently accepting it here would discard it forever. Either drop the numbering block or activate a mode in the same call.