Overview

Your client is a freelancer who also runs an S.L., so they invoice under two tax IDs. An accounting firm (gestoría) runs the invoicing of forty clients. Both are the same model, and this page explains it once; every other page in this section links back here.

The model

graph LR
A["Your account<br/>account_id"] -->|holds 1..N| C["Company = one NIF<br/>company_id"]
A -->|has| M["Members<br/>OWNER · ADMIN · MEMBER"]
M -.->|"grant VIEW / OPERATE<br/>(MEMBER only)"| C
A -->|"manages, at an access_level"| B["Managed account<br/>provisioned by you"]
B -->|holds 1..N| D["Company = one NIF"]

Four pieces, in this order:

1. Account — who pays and authenticates. It owns the subscription, the API keys, the webhooks and the people. Identified by account_id.
2. Companies — each NIF/CIF the account invoices under, with its own invoices, customers, products and series, kept apart in Test and Live. Identified by company_id. Throughout the docs and the API reference, Company always means one NIF. → Companies
3. Members and grants — the people with access to the account. An OWNER or ADMIN reaches every NIF; a MEMBER reaches only the NIFs they hold a grant on, at VIEW or OPERATE. → Members & grants, Invitations
4. Managed accounts — separate accounts that you provisioned for someone else. You pay for them and hold one access_level over each (NONE, VIEW or OPERATE); the holder can claim theirs later. → Managed accounts

An account is not a NIF: the account is who pays and authenticates, the NIF is who invoices. A freelancer with one NIF has one account and one company — the distinction only shows up at two.

Member or managed account?

Both give you access to somebody else's NIFs, and they are not interchangeable:

• The taxpayer signs up and pays for themselves, and wants your help → they invite you as a member of their account. Their account, their bill; you hold a role in it.
• You onboard them by API and you pay → you provision a managed account. Your bill; they can claim the account later without you losing your access.

Which credential acts on what

• An API key belongs to one account and is created by an OWNER or ADMIN of it (a MEMBER cannot create keys: 403 ACCOUNT_MANAGEMENT_FORBIDDEN). It reaches every NIF of that account, plus the NIFs of the accounts it manages, at the access_level held over each.
• Grants govern people in the dashboard. They decide what a MEMBER sees when signed in; they never apply to an API key.
• Scopes decide which operations a key may call; access decides where it may write. A key with invoices:write still cannot issue for a NIF you only hold at VIEW. The full scope catalog, including the two provisioning scopes, is in Scopes.
• The target is always the id in the path, never the credential. An API key is stateless and carries no notion of a "current" NIF.

Test and live keys

The base URL is the same; the key prefix picks the environment (Authentication). For everything that belongs to a NIF — invoices, customers, series, readiness, payment connections — a beel_sk_test_ key works on Test data and a beel_sk_live_ key on Live data.

The account's control plane is different: members, grants, invitations and your management of an account are not per environment. A collaborator is the same person with the same grants in Test and Live, so a change there is real whichever key makes it. That is why these writes refuse a test key:

Handing ownership over is dashboard-only. No API key can do it, a live one included, so a leaked key can never take the account. See Hand over ownership.

Two identifiers

# 1. Which account is this key?
curl https://app.beel.es/api/v1/me/identity \
  -H "Authorization: Bearer beel_sk_live_xxx"

# 2. Which NIFs does it hold?
curl https://app.beel.es/api/v1/accounts/3fa85f64-5717-4562-b3fc-2c963f66afa6/companies \
  -H "Authorization: Bearer beel_sk_live_xxx"

Where each identifier goes

Both identifiers travel in the path. Which one you use depends on whether the thing you are touching belongs to a NIF or to the account.

{company_id} — everything that belongs to one NIF, both configuring it and operating on it:

/v1/companies/{company_id}/invoices
/v1/companies/{company_id}/customers
/v1/companies/{company_id}/products
/v1/companies/{company_id}/series
/v1/companies/{company_id}/tax-configuration

The account that owns the NIF is derived from it, so there is no pair to keep coherent.

{account_id} — everything that belongs to the account: its list of NIFs, members, invitations, the accounts it manages, webhooks and request logs.

/v1/accounts/{account_id}/companies
/v1/accounts/{account_id}/members
/v1/accounts/{account_id}/webhooks

When it does not add up

Is a NIF ready to invoice?

curl https://app.beel.es/api/v1/companies/550e8400-e29b-41d4-a716-446655440000/issuing-readiness \
  -H "Authorization: Bearer beel_sk_live_xxx"

{
  "success": true,
  "data": {
    "ready": true,
    "blockers": [],
    "verifactu": { "ready": false, "blockers": ["NIF_NOT_REGISTERED"] }
  }
}

ready is true only when blockers is empty. Two things the answer depends on:

• The environment of your key. A beel_sk_test_ key asks about Test, a beel_sk_live_ key about Live, so the same NIF can be ready in one and not in the other — a NIF provisioned in Test is ready with a test key and reports COMPANY_NOT_ACTIVATED with a live one until you switch it on there.
• Which question you ask. ready / blockers say whether the NIF can issue. verifactu.ready / verifactu.blockers say whether its invoices would pass VeriFactu registration — a separate question. A Live NIF can be ready: true while verifactu.blockers still lists what AEAT registration needs.

Add ?include=readiness to GET /v1/accounts/{account_id}/companies to get the same answer for every NIF in one call. See Get the issuing readiness of a company.

Related