--- title: "Get the issuing readiness of a company" method: GET path: "/v1/companies/{company_id}/issuing-readiness" tags: ["Company"] --- # Get the issuing readiness of a company `GET /v1/companies/{company_id}/issuing-readiness` ## Request - Base URL: `https://app.beel.es/api` - URL: `https://app.beel.es/api/v1/companies/{company_id}/issuing-readiness` - Auth: HTTP bearer Returns whether a company can issue its STANDARD invoice right now in the environment of the request, and the `blockers` that stop it otherwise. Readiness is a per-NIF property, evaluated independently for each company of the account. - **`ready`:** `true` only when `blockers` is empty. - **Activation:** issuing any fiscal document requires the company to be activated in the environment of that document, whether or not it goes to VeriFactu. - **VeriFactu chain:** the AEAT census and signed representation are additionally demanded only when the company is under the VeriFactu regime in this environment — the same fact that decides, at issue time, whether its invoices are registered. A company with VeriFactu off is ready with a NIF, a default series and an activation, and the separate `verifactu` block reports the compliance chain independently. - **Not evaluated:** the account's quota or subscription, and the payload of any particular invoice. ## Response `200` Issuing readiness - IssuingReadinessResponse - `success` boolean - `data` IssuingReadinessData: Issuing-readiness of a company: whether it can issue its STANDARD invoice right now, in this environment, and — if not — exactly what is missing. `ready` is true only when `blockers` is empty. Issuing any fiscal document requires the company to be activated in that environment (`COMPANY_NOT_ACTIVATED` otherwise), whether or not it goes to VeriFactu. The VeriFactu capability chain (census, signature) is only demanded on top of that when the company is under the VeriFactu regime in this environment — the same fact that decides, at issue time, whether its invoices are registered. With VeriFactu off, a NIF, a default series and a live activation are enough to be ready. - `ready` boolean: true if the company can issue invoices (no blockers). - `blockers` string[]: Reasons the company cannot issue yet (empty when ready). Each one names what is missing and how to clear it: - `COMPANY_HAS_NO_NIF`: the company has no NIF. Set `nif` with `PATCH /v1/companies/{company_id}`; once set it cannot be changed. - `SERIES_DEFAULT_NOT_FOUND`: there is no default `STANDARD` invoice series in this environment. The `SIMPLIFIED` and `CORRECTIVE` ones are created on first use. `PUT /v1/companies/{company_id}/series/defaults` creates the missing ones, or mark an existing series with `PUT /v1/companies/{company_id}/series/{series_id}/default`. - `PROFILE_INCOMPLETE`: the fiscal identity is not complete enough to write an invoice header: entity type, legal name or full fiscal address is missing. Complete `entity_type`, `legal_name` and `address` with `PATCH /v1/companies/{company_id}`. A missing NIF is reported as `COMPANY_HAS_NO_NIF` instead, never as both. - `COMPANY_NOT_ACTIVATED`: the company is not activated in the environment of the request, and it is not under the VeriFactu regime. Activate it with `POST /v1/companies/{company_id}/activations` for that environment. - `ENV_MISMATCH`: the same missing activation, for a company under the VeriFactu regime. Activate it as above, or call with a credential of the environment where it is already activated. The first stage of the VeriFactu chain. - `NIF_NOT_REGISTERED`: the NIF is not registered for VeriFactu submission in this environment. Turning VeriFactu on (`PUT /v1/companies/{company_id}/verifactu-configuration` with `enabled: true`) registers it; in Live that call needs the signed representation first. Never reported in Test, where the NIF is registered with its first submission. - `NIF_REPRESENTATION_REQUIRED`: the NIF is registered, but there is no signed AEAT representation in force. Generate it with `POST /v1/companies/{company_id}/representation`, sign it digitally and send it with `POST /v1/companies/{company_id}/representation/submit`. Live only. - `verifactu` object: The compliance question, separate from the operational `ready` above: would this NIF pass a VeriFactu emission right now? Relevant before putting the company under the VeriFactu regime. For a company already under the regime, `verifactu.ready` coincides with `ready` (same evaluation). - `ready` boolean: true only when the company is operationally `ready` AND its VeriFactu capability chain is clean. An operational blocker (missing NIF, default series, or an incomplete fiscal identity) makes this false even if the chain itself is complete — and, since those are not chain stages, it does so with an EMPTY `blockers` list here. The reason is in the top-level `blockers`, which is where operational blockers are reported. - `blockers` string[]: ONLY the incremental VeriFactu capability stages, in order and mutually exclusive — one reason at a time, without repeating the operational blockers (NIF/series/fiscal identity) listed above. The stages, and how to clear each one, are the same as in the top-level `blockers`: - `ENV_MISMATCH`: the company is not activated in the environment of the request. - `NIF_NOT_REGISTERED`: the NIF is not registered for VeriFactu submission in this environment; turning VeriFactu on registers it. - `NIF_REPRESENTATION_REQUIRED`: no signed AEAT representation in force. Only appears where a signed representation is actually demanded (Live). - `meta` ResponseMeta - `timestamp` string, date-time - `request_id` string ## Other responses - `400`: The request target could not be read as declared, so nothing was looked up. Three causes, all named in `error.details`: a path or query parameter whose value does not parse as its type (`VALIDATION_ERROR` — a UUID that is not a UUID, an unknown enum value, an empty element in a list such as `status=ISSUED,`), a required parameter that was not sent (`MISSING_PARAMETER`), or a header that is meant to carry an identifier and does not (`ACTIVE_COMPANY_HEADER_INVALID`). A list parameter sent entirely empty (`status=`) is not an error: it is the same as omitting it. The fault is in the target, not in the content — which is what `422` is defined over. - `401`: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those. - `403`: Authenticated but not allowed. Fourteen causes shared by every operation, told apart by `error.code`; an operation that adds a cause of its own names it in its `403`. You can branch on them exhaustively. - `INSUFFICIENT_SCOPE` — the credential lacks a scope the operation requires; `error.details.missing_scopes` names them as a single comma-separated string (for example `"invoices:write,customers:read"`), not as an array; `required_scopes` has the same shape and lists every scope the operation needs. Retrying will not help: mint a key that holds them. - `COMPANY_READ_ONLY` — the scope is there, but your access level over that NIF only lets you read it. - `ACCOUNT_MANAGEMENT_FORBIDDEN` — the scope is there, but your role over the account, or the management relationship you hold over it, does not cover this operation. - `ACCOUNT_NOT_ACCESSIBLE` — the account is not yours to reach, which is also the answer when it does not exist, so existence is never disclosed. - `ACTIVE_COMPANY_NOT_ACCESSIBLE` — the same, for a NIF: the company in the path, or the one named by `BeeL-Active-Company`, is not one this credential may reach — and again, this is also the answer when it does not exist. - `COMPANY_ACCESS_REVOKED` — your access to the NIF was withdrawn while the request was already in flight, so the write was rejected and nothing was recorded. Retrying will not help until the access is granted again. - `LIVE_CREDENTIAL_REQUIRED` — the operation changes the real account and the call came from a test API key (`beel_sk_test_…`). Use your live key or the dashboard. - `FEATURE_NOT_AVAILABLE` — your subscription does not include the entitlement the operation needs; `error.details.feature_code` names it. This gate runs **before** the scope gate, so for such an operation you never see `INSUFFICIENT_SCOPE` first. - `NO_ACTIVE_ACCOUNT` — the credential does not resolve to an account, so no scope can be evaluated against one. Fail-closed, not a permission that can be granted to you. - `OPERATION_REQUIRES_SESSION` — the operation is available only from the web session; no API key and no OAuth2 token can perform it, whatever scopes it holds. - `OPERATION_REQUIRES_API_KEY` — the reverse: the operation needs a scope that only an API key can hold (such as `accounts:write`), so a dashboard session never satisfies it. - `API_KEY_LIVE_NOT_AVAILABLE` — the call came with a live API key (`beel_sk_live_…`) and the account has no Live mode yet. It is never degraded to Test: use your test key, or activate Live first. - `ACCOUNT_REQUIRES_FOCUS_SWITCH` — dashboard session only: you are a member of the account in the path, but it is not the account in focus. Switch focus to it and retry. - `REQUEST_BLOCKED` — the edge security filter stopped the request before the API saw its body, usually because a text field carries something that looks like markup or a script (HTML tags, `