Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. By signing up you are subscribing to the APIs.io and API Evangelist
newsletters — you can unsubscribe from any issue. See our
Privacy Policy and Terms.
openapi: 3.2.0
info:
title: BeeL. Public Configuration Tax API
description: 'Public invoicing API for self-employed professionals in Spain with VeriFactu regulatory compliance. Authenticate using API Keys (`Authorization: Bearer `). Keys are scoped and environment-aware:
`beel_sk_live_*` targets production, `beel_sk_test_*` targets sandbox (no quota consumed, VeriFactu test mode). Every operation declares the scope it requires in its `x-required-scopes` extension, and the
reference at docs.beel.es shows it next to the operation''s title. Create the key with (at least)
those scopes; a key that is short of one is answered `403`. The full catalogue is in the
`ApiKeyAuth` security scheme below. OAuth2 is reserved for BeeL''s own official clients (the MCP bridge and the CLI) and is not part of
the public contract at present. There is no dynamic client registration and no way for a third
party to obtain a `client_id`, so the API key is the credential to integrate with. POST endpoints, and the PUT/PATCH/DELETE operations that list it, accept an `Idempotency-Key` header (any unique client-generated string) to retry a request safely without repeating it. A retry with the same key within 24 hours replays the first response when it was a success (2xx) or a server error (5xx), with the header `Idempotency-Replay: true`; a 4xx is not stored, so the corrected request can reuse the key. See the header parameter for the details. **This specification is served live by the API itself**, at
`https://app.beel.es/api/v1/openapi.yaml` (and `.json`) — the same document this reference is
built from, so you can point a generator or a viewer straight at it. **Response envelope.** Every JSON response is wrapped in `{success, data, meta}`. Bare
resources are not part of the contract. Read the payload through `data` and you never have to
branch on the shape of the body. - A **single resource** travels as an object in `data`: `data: {id, ...}`. - A **collection** travels under a named key inside `data`, alongside its `pagination`, also
inside `data`: `data: {invoices: [...], pagination: {...}}`. The key is named after the
resource, so a response never hides which collection it carries. - A collection is paginated unless the operation declares itself a **closed catalogue** — a
fixed, bounded list (tax types, customisation options) that has nothing to page through. Only
an explicit declaration in the operation makes a collection unpaginated; the absence of
`pagination` is never something to infer. - `GET /v1/accounts` paginates by **cursor** (`data: {accounts: [...], next_cursor}`) instead of
by page. That is a documented variant of pagination, not a different envelope: it is still a
named collection inside `data`. Which of the three a collection is, is declared and machine-readable, so no consumer has to
guess: the operation either carries `pagination` in its response schema, or the extension
`x-closed-catalogue: true`, or `x-pagination-style: cursor`. Those three cases are the whole
list, and a collection that declares none of them is a defect in this contract, not a fourth
variant to code around. A contract ratchet in CI enumerates exactly that. A `data` holding the array directly, with `pagination` as its sibling, is arguably the nicer
shape and is what a v2 of this contract would adopt. It is **not** what v1 does, and v1 will not
be flipped to it: live integrations read `data.` today, and no ergonomic gain justifies
breaking them without a version to move to. Operations on their way out are the one exception, and they are frozen rather than fixed. An
operation that is `deprecated` and announces a `Sunset` date keeps whatever shape it shipped
with — `GET /v1/products/search` is the last one whose `data` is a bare array — because
reshaping a route that is about to be removed only breaks the integrations still on it. Its
description says what the successor answers instead. Every operation without a retirement date
obeys the rule above. Query parameters are strict, across every endpoint.'
version: 1.9.0
contact:
name: BeeL. Technical Team
email: it@beel.es
url: https://beel.es
license:
name: Proprietary
url: https://beel.es/license
x-agent-resources:
openapiJson: https://beel.es/openapi.json
openapiYaml: https://beel.es/openapi.yaml
source: https://docs.beel.es/api/openapi
authorizationServerMetadata: https://app.beel.es/api/.well-known/oauth-authorization-server
llmsFull: https://docs.beel.es/llms-full.txt
mcpServer: https://mcp.beel.es/mcp
x-onboarding:
signupUrl: https://app.beel.es/signup
selfServeApiKeys: true
freeTier: sandbox ilimitado, sin tarjeta
sandbox:
keyPrefix: beel_sk_test_
sameBaseUrl: true
aeatTestMode: true
quotaConsumed: false
liveKeyPrefix: beel_sk_live_
salesContactRequired: false
zeroAuthEndpoints:
- https://beel.es/openapi.json
- https://beel.es/api/health
- https://beel.es/agents.md
x-cli:
package: '@beel_es/cli'
npm: https://www.npmjs.com/package/@beel_es/cli
quickstart: npx @beel_es/cli --help
x-agent-instructions: https://beel.es/agents.md
servers:
- url: https://app.beel.es/api
description: Production server
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://artifacts.apis.io/beel-es/openapi/beel-es-configurationtax-api-openapi.yml