Get invoice stats per company
Scopecompanies:listReturns, for each company of the account, how many fiscal documents it has issued and when it last issued one.
invoice_count: drafts, scheduled invoices and proformas are not counted; a rectifying invoice counts as a document of its own, and a voided invoice counts only when a live rectifying invoice compensates it.last_invoice_at: issue date of the most recent document in that same set, ornullwhen there is none.- Not a cursor: the count is not monotonic — voiding an uncompensated invoice
lowers it and moves
last_invoice_atbackwards — so do not synchronise on it.
Paginated with the usual page/limit, and the usual defaults: without them you get
the stats of the first 20 companies, not of all of them. One row per company, over the same
universe and in the same order as GET /v1/accounts/{account_id}/companies — search
included — so asking both with the same page, limit and search lines the two
responses up company by company.
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
Your own account, or an account you provisioned. It — not the credential — decides which account the operation acts on; a 403 is returned when you do not reach it, the same response an account that does not exist gets.
uuidQuery Parameters
Page number, starting at 1. The response echoes it back as pagination.current_page.
11 <= valueHow many items to return per page. The response echoes it back as pagination.items_per_page.
201 <= value <= 100Case-insensitive filter on NIF, legal name or trade name — the same filter, over the same universe, as the one GET /v1/accounts/{account_id}/companies applies. Blank or omitted returns all.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/companies/stats"{
"success": true,
"data": {
"stats": [
{
"company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
"invoice_count": 42,
"last_invoice_at": "2026-05-12T00:00:00Z"
}
],
"pagination": {
"current_page": 1,
"total_pages": 5,
"total_items": 87,
"items_per_page": 20,
"has_next": true,
"has_previous": true
}
},
"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": "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": "VALIDATION_ERROR",
"message": "Validation constraint violation.",
"details": {
"limit": "must be greater than or equal to 1"
}
},
"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"
}
}List the companies of an account GET
Returns the companies (NIFs) belonging to the account in the path, ordered with the primary company first. An account with no companies yet returns an empty list rather than an error. - **`search`:** filters case-insensitively on NIF, legal name and trade name. - **`include=readiness`:** adds each company's issuing-readiness block. - **Paginated**, always: without `page` and `limit` you get the first 20 companies, not all of them, and `pagination` is present in every response — a single-company account simply gets a one-item page. - **Series:** not part of this response. Read them from `GET /v1/companies/{company_id}/series`.
Get a company GET
Returns the identity and activation state of a company: its fiscal data, whether it is switched on in Test and in Live, and its VeriFactu registration state. It also returns **every field `PATCH /v1/companies/{company_id}` accepts** — contact details, legal representative, bank details, IAE, activity start date, payment term and the rendering block — so what was written can be read back without keeping a copy of it. A field never set comes back absent: that means "nothing stored", not "hidden". Its invoice series are not part of this response: read them from `GET /v1/companies/{company_id}/series`.