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. The street number is mandatory here: an address without it is rejected with 422.

Addresses you read back are described by their own schema, and do not guarantee the street number: records registered before it was collected have none.

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)

Complete tax information with cross-validations:

• IVA: real rates 4, 5, 10, 21 (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 4, 5, 10 and 21 for IVA and not 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 % (RD-ley 11/2022 and its extensions, on electricity, gas and basic foodstuffs) is no longer in force for new operations, but it stays valid: corrective invoices and late-filed invoices for the periods when it applied must be able to carry it. Its equivalence surcharge pair is 0.625.

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 its numbering is frozen by law: 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.

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 NIF profile 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 NIF profile is created. The company 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.