beel-es Proforma API

openapi: 3.2.0
info:
  title: BeeL. Public Proforma 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 (106 KB total) ---
# Full source: https://artifacts.apis.io/beel-es/openapi/beel-es-proforma-api-openapi.yml