NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Companies

Get the issuing readiness of a company

Scopecompanies:read

Returns whether a company (NIF) 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 applies VeriFactu by default, the same derivation invoice creation uses when verifactu_enabled is omitted. A company with VeriFactu off is ready with a NIF, a default series and an activation. Issuing an invoice with an explicit verifactu_enabled: true still enforces the full chain at emission time regardless of this answer, and the separate verifactu block reports that chain independently of the setting.
  • Not evaluated: the account's quota or subscription, and the payload of any particular invoice.
GET
/v1/companies/{company_id}/issuing-readiness

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

NIF (company) whose issuing readiness is evaluated. 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 NIF you do not reach answers 403, and so does a NIF that does not exist.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/issuing-readiness"
{
  "success": true,
  "data": {
    "ready": true,
    "blockers": [
      "COMPANY_HAS_NO_NIF"
    ],
    "verifactu": {
      "ready": true,
      "blockers": [
        "ENV_MISMATCH"
      ]
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
    "details": {
      "field": "invoice_id",
      "invalid_value": "deliveries",
      "expected_format": "UUID"
    }
  },
  "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": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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"
  }
}

Switch a company off DELETE

Switches the company (NIF) 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.

Generate the representation document POST

Generates the unsigned AEAT representation PDF of a company (NIF), the first step of the representation flow. - **Next steps:** download the PDF from `GET /v1/companies/{company_id}/representation/document`, sign it digitally and return it through `POST /v1/companies/{company_id}/representation/submit`. - **Fiscal identity:** must be complete before the document can be produced. An incomplete one is rejected with `400` naming what is missing. - **Existing representation:** a company that already holds an active one is rejected too. Cancel it first.