beel-api

BeeL API — Integration Guide

BeeL is a SaaS invoicing platform for Spanish autónomos with full VeriFactu compliance.

⚠️ Golden Rules

1. NEVER invent endpoints, fields, or package names. Always verify against the live docs first — see "How to Look Up Documentation" below for the token-efficient way to do it.
2. NEVER hardcode API keys. Always use environment variables (process.env.BEEL_API_KEY).
3. There is NO separate test URL. Base URL is always https://app.beel.es/api, and every path starts with /v1/. The key prefix determines the environment: beel_sk_test_* = sandbox, beel_sk_live_* = production.
4. Company-scoped paths are the canonical form. Build new code against /v1/companies/{company_id}/… (invoices, customers, products, series, tax and VeriFactu settings). The flat routes (/v1/invoices, /v1/customers, /v1/products, /v1/configuration/* and their sub-paths like /issue and /void) are deprecated: true, each carrying an x-successor; they keep working until the date in their Sunset response header.
5. Send BeeL-Active-Company (the company_id) on any request touching company-owned data. Optional on an account with a single NIF, required on an account with several — otherwise 403 ACTIVE_COMPANY_REQUIRED. See /beel-api:multi-nif.
6. Idempotency-Key on POST. Ignored on PUT/PATCH/DELETE unless the operation opts in. Optional in general, required on bulk imports. See recipes/invoice-flow.md.
7. Issued invoices are immutable. To correct → corrective invoice. To cancel → void it.
8. When in doubt, look up the docs (see below).

📚 How to Look Up Documentation

Preferred: the BeeL CLI docs search — and propose it to the user first.

When you need to check the docs, don't silently fetch the whole llms.txt / llms-full.txt (that burns tokens and pulls in ~600KB you don't need). Instead, suggest running the CLI and wait for the user's go-ahead, e.g.:

"I need to confirm the exact fields for creating an invoice. Want me to run npx @beel_es/cli docs search create invoice? It searches the docs locally and returns only the matching ~2KB section — no API key needed."