NewStripe: a buyer with a NIF always gets a standard invoice, and the simplified threshold is deprecated
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Companies

Switch a company on

Scopecompanies:write

Switches an existing company on in the mode carried in the body. The mode is always explicit and never taken from the credential's environment, so a Test key can switch a NIF on in Live.

Modes and billing

  • TEST: immediate and free.
  • PROD: immediate when the account already has a card on file or an enterprise contract, and the NIF is added to the existing subscription. With no card on file it answers 402 CHECKOUT_REQUIRED, returning a checkout_url when success_url and cancel_url are supplied. It also requires being the billing subject of the account (403 NOT_BILLING_OWNER otherwise).
  • billing_period: picks the plan the checkout sells — MONTHLY (default) or ANNUAL. It only matters when a checkout is opened. Accounts with a negotiated rate or an enterprise contract cannot buy the annual plan (422 ANNUAL_PLAN_NOT_AVAILABLE).

Idempotency and pending switch-offs

  • Repeating the call: opens no second checkout and adds no second subscription item; it returns the existing activation with already_active: true. The same Idempotency-Key sent to this route and to the nested one it replaces is the same operation, so it is replayed and never charged twice.
  • A pending switch-off is cancelled: while it is pending the NIF is still on — it just carries an effective date — so switching it on again only removes that date, answers scheduled_deactivation_cancelled: true, and charges or credits nothing. It does commit the NIF to the next billing cycle, though, so under an agreement capped at a number of Live NIFs it asks for a seat like a new NIF would, and is rejected with 409 NIF_LIMIT_REACHED when the cap is already full.
POST
/v1/companies/{company_id}/activations

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Path Parameters

company_idstring

Unique identifier (UUID) of the company being switched on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.

Formatuuid

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)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses 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 for the Retry-After seconds (2) 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

environmentstring

Mode a record lives in — its Test/Live twin. It decides where invoices, customers and quota are accounted.

For a company it also decides which AEAT its NIF is registered against: switching a company on in PROD is what registers it with the real AEAT, so aeat_environment is that same mode and uses this same enum.

Value in"TEST" | "PROD"
success_url?string

Where Stripe returns after the card is captured. Only used when switching on in Live with no card on file. May embed Stripe's {CHECKOUT_SESSION_ID} template, which is why it is a plain string and not a uri: the braces are not legal URI characters.

cancel_url?string

Where Stripe returns if the checkout is abandoned.

Formaturi
billing_period?string
Value in"MONTHLY" | "ANNUAL"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/activations" \  -H "Content-Type: application/json" \  -d '{    "environment": "PROD"  }'
{
  "success": true,
  "data": {
    "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
    "environment": "PROD",
    "already_active": true,
    "scheduled_deactivation_cancelled": true
  },
  "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 is required 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": "The invoice must have at least one line",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "CONTACT_SALES_REQUIRED",
    "message": "To add more than one NIF, talk to us: we will prepare a per-NIF price for you.",
    "details": {
      "reason": "LIVE_WITH_MULTIPLE_NIFS",
      "salesUrl": "https://beel.es/ventas"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "NIF_PROD_ALREADY_ACTIVE_IN_ANOTHER_ACCOUNT",
    "message": "This NIF is already registered in production under another account. A NIF can only issue real invoices from a single account.",
    "details": {}
  },
  "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": "The invoice must have at least one line",
  "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"
  }
}
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Delete a company DELETE

Removes a company from the account: it stops appearing and stops being billed. - **Existing invoices:** those already issued are retained, but the company-scoped API can no longer resolve them once the NIF is removed. - **What blocks removal:** a NIF activated in Live (`409 COMPANY_ACTIVE_IN_PRODUCTION`), one holding any invoice in Live — issued, draft or proforma (`409 COMPANY_HAS_INVOICES`) — and the account's primary NIF (`400 CANNOT_DELETE_PRIMARY`). - **Deactivating first:** switching off in Live is scheduled to the end of the paid cycle, so the removal only becomes possible once that takes effect. - **Test:** NIFs never activated, or activated only in Test, are removed right away, and invoices in Test never block. - **`Idempotency-Key`:** without one, a retry after a timeout answers `403` instead of the original `204`.

Switch a company off DELETE

Switches the company off in the mode given by `environment`; the other mode is untouched. - **Sealed, not deleted:** the activation's history survives. After the switch-off takes effect the NIF can neither issue nor correct invoices in that mode until it is switched on again, and in Live that sealing is what releases the NIF for another account. ## When it takes effect - **In Live the switch-off is scheduled, not immediate:** the cycle is paid up front, so the response carries an `effective_at` and the NIF keeps invoicing until then. Nothing is refunded. `effective_at` is the end of the current billing cycle, unless the NIF was switched on within that same cycle, in which case it is the end of the next one. - **`TEST`, and `PROD` under an enterprise contract:** immediate, and answer with no `effective_at`. ## Repeats and permissions - **Repeating the call:** on a mode whose switch-off is already pending it returns the same date with `already_scheduled: true`; switching off a mode that was never on is a silent no-op. - **Permission:** switching off in Live requires being the billing subject of the account.