multi-nif

BeeL Multi-NIF — Integration Guide

BeeL's multi-NIF model lets one account (one API key) hold many companies, each a Spanish tax ID (NIF/CIF) with its own fully isolated invoices, customers, products and series. Built for professionals with several NIFs, agencies (gestorías) and fleets that invoice on behalf of the businesses they manage.

The golden rules in the beel-api skill apply throughout — especially: never invent endpoints, fields or scopes; verify against the live docs.

The model (know this before writing code)

access_level is one single vocabulary — NONE (no visibility), VIEW (read-only), OPERATE (read and write) — used both for a member's grant over a company and for a provisioner's access over a managed account. It never decides who pays: billing follows the provisioning relationship, not the access level.

Members vs managed accounts — pick the right one

Both give access to operate a business, but point in opposite directions. Don't require both scopes — an integration uses one model:

• Members (members:*) — a person joins an account that already exists. The owner, billing and NIF stay with that account; the invitee only needs a login (not an account of their own) and does no fiscal onboarding. Use when the client signed up and pays themselves and invites you in.
• Managed accounts (accounts:write) — you create and run a third party's account (its own NIF, its own billing) and they can later claim it. Use when you onboard them by API and you pay (fleets, mass onboarding, platform gestorías whose clients aren't on BeeL yet).