NewTell a voided invoice from a totally rectified one, without a second call
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Accounts

Provision an account

Scopeaccounts:write

Provisions a new account on BeeL. and returns a one-time claim_token to deliver to the account holder so they can set their password and take ownership. The holder can be an self-employed individual or a legal entity. Privileged: requires the accounts:write scope (only on your provisioner key). Idempotent by external_ref. Use access_level to choose the management level you keep over the account (default: billing only — you pay their subscription but do not see their data).

If you previously ended your management of this account (DELETE /v1/accounts/{account_id}/management) and its holder has not claimed it yet, provisioning the same email reactivates that account instead of creating a new one: the same account, holder, NIFs and invoices come back under your management, with the external_ref and access_level of this request, and it counts towards your billable usage again. Once the holder has claimed the account it is theirs, and only they can grant you access again.

POST
/v1/accounts

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

Obtaining Keys: API Keys are managed from the BeeL dashboard

Security: API Keys are secret credentials. Do not share them or store them in source code

In: header

Header Parameters

Idempotency-Key?string

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • If the same key is sent twice, the result of the first operation is returned
  • Keys expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Request Body

email?string

Optional. Email address of the account holder, used as their login. Omit it to create the account without a person: no login, no person_id and no claim_token. You can add the holder later with POST /v1/accounts/{account_id}/claim-tokens. Required when send_email is true (there is nobody to write to otherwise) — else 422.

Formatemail
display_namestring

Human-readable name for the account. Must not be blank.

Length1 <= length <= 255
external_refstring

Your own identifier for this account in your system. Used as an idempotency key: re-provisioning with the same external_ref returns the existing account (201, not 409).

language?string
Value in"es" | "en" | "ca"
access_level?string
Value in"NONE" | "VIEW" | "OPERATE"
tax_profile?
send_email?boolean

Optional. When true, BeeL emails the account holder a claim link (/reclamar?token=...) so they can set their password and take ownership. Defaults to false: by default you receive the claim_token in the response and deliver it yourself. Requires a deliverable email: sending true without one returns 422.

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/accounts" \  -H "Content-Type: application/json" \  -d '{    "display_name": "string",    "external_ref": "string"  }'
{
  "success": true,
  "data": {
    "person_id": "087e858e-473c-4f50-b5b0-c1df6c021550",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "status": "PROVISIONED",
    "claim_token": "string",
    "claim_url": "http://example.com",
    "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission 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": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}
{
  "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"
  }
}

Get the fiscal summary of a company for a period GET

Returns the VAT and IRPF summary of the invoices issued under this company (NIF) for the requested period, together with the annual IRPF projection and its progressive bracket breakdown. The period defaults to the current month and may not exceed 365 days. Requires the `invoices:read` scope.

Issue a claim token for an account you provisioned POST

Issues a single-use `claim_token` for an account you provisioned, so its holder can set a password and take ownership. Privileged: requires the `accounts:write` scope. It serves the two moments the alta cannot: **giving a holder to an account provisioned without `email`** (send the holder's address in the body and the person is created here, not at provisioning time), and **re-issuing a token that expired** — they last 30 days, which with a large portfolio starts to bite in the second month. **This is not the member invitation of `/v1/accounts/{account_id}/invitations`.** That one invites an extra person into an account that already has a holder; this one hands the account itself over to its holder. It is the counterpart of the private claim flow the holder completes, not a second way of doing it. **Tokens are a collection with a single live element**: issuing again invalidates the previous token — the old link stops working the moment you ask for a new one. A `404` is returned when the account was not provisioned by you or does not exist (existence is not disclosed).