# List the compliance submissions of an invoice API Reference

Returns every submission of this invoice to the tax systems it is owed to, VeriFactu
included, each with its own status, ordered by `submitted_at` ascending (queued ones,
still without it, last). The invoice's `compliance` summarises where it stands with each
system; this resource lists what was sent to get there.

- **No submissions:** an invoice that was never submitted (a draft, a proforma, or one
  the company does not report through BeeL.) answers `200` with an empty list.

**Closed catalogue.** This collection is fixed and bounded: it carries no `pagination`, it
takes no `page`/`limit`, and every response holds the whole set.


## GET /v1/companies/{company_id}/invoices/{invoice_id}/compliance-submissions

**List the compliance submissions of an invoice**

Returns every submission of this invoice to the tax systems it is owed to, VeriFactu
included, each with its own status, ordered by `submitted_at` ascending (queued ones,
still without it, last). The invoice's `compliance` summarises where it stands with each
system; this resource lists what was sent to get there.

- **No submissions:** an invoice that was never submitted (a draft, a proforma, or one
  the company does not report through BeeL.) answers `200` with an empty list.

**Closed catalogue.** This collection is fixed and bounded: it carries no `pagination`, it
takes no `page`/`limit`, and every response holds the whole set.

### Authentication

Accepts any of:

- `ApiKeyAuth` (HTTP bearer, token format `beel_sk_*`)

### Parameters

- **company_id** (required) in path `string`: Unique identifier (UUID) of the company the operation acts 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.
- **invoice_id** (required) in path: Invoice ID

### Responses

#### 200: Compliance submissions retrieved successfully

**Content `application/json`:**

- **success** (required) `boolean`: No description (example: true)
- **data** (required): The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1.
- **meta** `ResponseMeta`
- **data** `object`: No description
  - **submissions** (required) `array[InvoiceComplianceSubmission]`: No description

**Example:**

```json
{
  "success": true,
  "data": {
    "submissions": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "type": "VERIFACTU",
        "operation": "ISSUE",
        "status": "FULFILLED",
        "system_status": "verifactu:ACCEPTED",
        "error_code": null,
        "error_message": null,
        "submitted_at": "2026-11-12T10:15:01Z",
        "updated_at": "2026-11-12T10:15:03Z"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-11-12T10:20:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 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.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "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"
  }
}
```

#### 401: Missing or invalid authentication. `error.code` is `UNAUTHORIZED`, except for an access
token of BeeL's automations client whose authorization has been revoked (the user revoked
the connection, or was removed from the account it was granted for): then it is
`OAUTH_AUTHORIZATION_REVOKED`. Any other OAuth token answers `UNAUTHORIZED`.
Refreshing the token will not help; the user has to connect again. 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.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 403: Your account does not own or manage this company, or does not hold the required
access over it. A NIF that does not exist answers the same way.
That case answers `error.code` `ACTIVE_COMPANY_NOT_ACCESSIBLE`.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

#### 404: The resource addressed by the path does not exist, or is not one this credential can see —
the two are answered identically, so existence is never disclosed. `error.code` names the
kind of resource that was missing, so a client can tell which of several ids in a path
failed to resolve:

- `INVOICE_NOT_FOUND` — the `{invoice_id}` (invoices, proformas and their sub-resources).
- `RECURRING_NOT_FOUND` — the `{recurring_invoice_id}`.
- `CLIENT_NOT_FOUND` — the `{customer_id}`.
- `INVOICE_CLIENT_NOT_FOUND` — the `customer_id` referenced by an invoice body does not
  resolve to a customer of the issuing company.
- `INVOICE_SERIES_NOT_FOUND` — the `series_id` of an invoice body does not resolve to a series
  of the issuing company and environment.
- `PRODUCT_NOT_FOUND` — the `{product_id}`.
- `SERIES_NOT_FOUND` — the `{series_id}`.
- `WEBHOOK_SUBSCRIPTION_NOT_FOUND`, `DELIVERY_LOG_NOT_FOUND` — the `{webhook_id}` and the
  `{delivery_id}`.
- `PROFILE_NOT_FOUND` — the credential's account has no company profile yet: its holder
  has not completed onboarding, so there is no issuer to act as.
- `NOT_FOUND` — the generic fallback, for the few resources that carry no code of their own.

Some resources declare a more specific `404` response of their own (`CONNECTION_NOT_FOUND`,
`MEMBER_NOT_FOUND`, `GRANT_NOT_FOUND`, `INVITATION_NOT_FOUND`, `REQUEST_LOG_NOT_FOUND`); it
is documented on the operation.

A `404` with `ENDPOINT_NOT_FOUND` is a different answer: the **path itself** does not exist
in this API (a typo in the route, or a resource that was never here). It says nothing about
any resource. When the path exists but not with that method, the answer is `405`, not `404`.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "success": false,
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice not found"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### 429: Rate limit exceeded. `RATE_LIMIT_EXCEEDED` when the request rate of your credential is
over its limit; `TOO_MANY_REQUESTS` when an email the operation sends is held back because
too many went out to that recipient in a short time. Either way, retry after the
`Retry-After` seconds.

`QUOTA_EXCEEDED` is the other `429`: the operation would go over a quota of your plan
for the current period (issued invoices, for instance). Retrying does not help until the
quota resets or the plan changes. `error.details` carries `feature_code`,
`current_usage`, `quota_limit` and `reset_date`, and `RateLimit-Reset` the seconds until
the reset when it is known.


**Headers:**

- `Retry-After` `integer`: Seconds until the rate limit resets
- `RateLimit-Limit` `integer`: Maximum requests allowed in the window
- `RateLimit-Remaining` `integer`: Remaining requests in the current window
- `RateLimit-Reset` `integer`: Seconds until the current window resets

**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "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"
  }
}
```

#### 500: Internal server error

**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

#### default: Any status code the operation does not list above. Every operation declares it, so a
generated client always has a branch to fall into and never loses the cause of a failure
it did not anticipate.

This is where the transport-level answers land — `405`, `406`, `415` and `429` — together
with any status a future version of the API starts returning. All of them carry the same
error envelope as the codes listed explicitly, so `error.code` is what tells them apart:
switching on the status code alone is not enough. See «Transport-level errors» in the
API description for when each one is produced.

A `402` carrying `SUBSCRIPTION_REQUIRED` lands here when the account has no active
subscription. `error.details` says why and what to do: `current_status` (absent if it
never had one), `required_permission` and `action`.

A `503` carrying `SERVICE_UNAVAILABLE` lands here too, with a `Retry-After` header: a
dependency of BeeL itself (the database, the email provider) was momentarily
unavailable and nothing was done. Retry after those seconds.

A `502` carrying `EXTERNAL_SERVICE_ERROR` also lands here: an outbound integration the
operation depends on failed or did not answer in time. It is a transient condition — retry
with the same `Idempotency-Key` where the operation accepts one.

One exception to the envelope: a failure of the network edge that never reaches the
application (`502`, `503`, `504`, `524`) is generated by Cloudflare and its body is not
BeeL's — it may not even be JSON. Treat those as "no answer", and retry.


**Content `application/json`:**

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

**Example:**

```json
{
  "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"
  }
}
```

---

# Related Schema Definitions

## SuccessResponse

The envelope every successful JSON response of the BeeL. API is wrapped in. There are no
bare resources in v1 and none are planned: the payload always hangs off `data`.

- A **single resource** is an object in `data`.
- A **collection** hangs off a named key inside `data`, together with its `pagination`,
  also inside `data` — `data: {invoices: [...], pagination: {...}}`.
- A collection carries `pagination` unless its operation declares itself a **closed
  catalogue**: a fixed, bounded list with nothing to page through. The declaration is
  explicit in the operation; a missing `pagination` is never something to infer.
- `GET /v1/accounts` pages by cursor (`data: {accounts: [...], next_cursor}`). It is a
  documented variant of pagination, not another envelope.

Putting the array straight into `data` with `pagination` as its sibling is the shape a v2
would adopt; v1 is not being flipped to it.

- **success** (required) `boolean`: No description (example: true)
- **data** (required): The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1.
- **meta** `ResponseMeta`

## ResponseMeta

- **timestamp** `string` (date-time): No description (example: "2025-01-15T10:30:00Z")
- **request_id** `string`: No description (example: "4bf92f3577b34da6a3ce929d0e0e4736")

## InvoiceComplianceSubmission

One submission of an invoice to one tax system, with its own status.

- **id** (required) `string` (uuid): Submission ID. For `type` `VERIFACTU`, the same value as `id` in `GET .../verifactu-records` and as `verifactu_registration_id` in the `verifactu.status.updated` webhook event. (example: "7c9e6679-7425-40de-944b-e07fc1f90ae7")
- **type** (required) `ComplianceSystem`: A tax system the AEAT requires invoices to be reported through. It is used both for the systems an invoice is owed to and for the systems a company reports through. * `VERIFACTU`: registration with the AEAT under VeriFactu. * `SII`: the AEAT ledger of issued invoices (Immediate Supply of Information). Available under contract. More systems will be added: ignore an invoice entry or a company period whose system you do not know.
- **operation** (required) `InvoiceComplianceSubmissionOperation`: What a submission asks the system to do with the invoice. * `ISSUE`: record the invoice. * `CORRECT`: replace what was recorded, after the system rejected it or accepted it with errors. The invoice itself does not change. * `CANCEL`: cancel the invoice in the system, after it was voided.
- **status** (required) `InvoiceComplianceStatus`: Where an invoice stands with one tax system, in the same vocabulary for every system. The status of the system itself is in `system_status`. * `NOT_SUBMITTED`: nothing has been sent yet. * `IN_PROGRESS`: sent, or queued to be sent, with no final answer yet. No action is needed while it stays in this status. * `FULFILLED`: the system accepted it. * `FULFILLED_NEEDS_FIX`: the system accepted it but reported errors in the data; review them and tell the user. * `REJECTED`: the system did not accept it, so it does not count. For VeriFactu, it has to be sent again once the cause is fixed. For SII, BeeL. sends it again and you do not need to do anything: `invoice.compliance.updated` is delivered when the status changes, and the submission in `compliance-submissions` gives the reason in `error_code`. If the customer's NIF or name is not in the AEAT census, sending it again leaves the status in `FULFILLED_NEEDS_FIX`. If the cause is in data that only you can correct, BeeL. contacts you. * `CANCELLED`: the system accepted its cancellation.
- **system_status** (required) `InvoiceComplianceSystemStatus`: The status as the system itself states it, as `<system>:<CODE>` (for example `verifactu:ACCEPTED_WITH_ERRORS`). Informational: branch on `status`, which says the same in a vocabulary shared by every system. Null while nothing has been sent.
- **error_code** (required) `string`: Code of the error the system reported on this submission, or of the reason BeeL. rejected it before sending. Null when there is none. (example: "1105")
- **error_message** (required) `string`: Human-readable reason for the outcome: the system's own description when it reported one, or a message written by BeeL. when BeeL. decided the outcome. Null when there is none. (example: "NIF del emisor no registrado")
- **submitted_at** (required) `string` (date-time): When the submission was sent. Null while it is queued. (example: "2026-11-12T10:15:01Z")
- **updated_at** (required) `string` (date-time): When the status of the submission last changed. (example: "2026-11-12T10:15:03Z")

## ErrorResponse

Error response shared by all BeeL. APIs.

The payload carries **two contracts at once** (additive, non-breaking):

- **Legacy** (`success`, `error.{code,message,details}`, `meta`) — kept
  intact for existing consumers.
- **RFC 9457** (`type`, `title`, `detail`, `instance`) — new fields
  for integrators following Problem Details for HTTP APIs. The
  `type` URI is the stable, shareable link to the error's
  documentation page (e.g. `https://docs.beel.es/errors/{code}`).

Future migration: the legacy fields will be deprecated via
`Deprecation`/`Sunset` headers after a sufficient adoption window,
and the response Content-Type will move to
`application/problem+json`.

- **success** (required) `boolean`: No description (example: false)
- **error** (required) `ErrorDetail`
- **meta** `ResponseMeta`
- **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES")
- **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES")
- **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line")
- **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123")

## ErrorDetail

- **code** (required) `string`: No description (example: "VALIDATION_ERROR")
- **message** (required) `string`: No description (example: "The provided data is not valid")
- **details** `object`: No description (example: {"field":"specific error message"})

## ComplianceSystem

A tax system the AEAT requires invoices to be reported through. It is used both for the
systems an invoice is owed to and for the systems a company reports through.

* `VERIFACTU`: registration with the AEAT under VeriFactu.
* `SII`: the AEAT ledger of issued invoices (Immediate Supply of Information). Available
  under contract.

More systems will be added: ignore an invoice entry or a company period whose system you
do not know.

Type: `string`

## InvoiceComplianceSubmissionOperation

What a submission asks the system to do with the invoice.

* `ISSUE`: record the invoice.
* `CORRECT`: replace what was recorded, after the system rejected it or accepted it with
  errors. The invoice itself does not change.
* `CANCEL`: cancel the invoice in the system, after it was voided.

Type: `string` — one of: ISSUE, CORRECT, CANCEL

## InvoiceComplianceStatus

Where an invoice stands with one tax system, in the same vocabulary for every system.
The status of the system itself is in `system_status`.

* `NOT_SUBMITTED`: nothing has been sent yet.
* `IN_PROGRESS`: sent, or queued to be sent, with no final answer yet. No action
  is needed while it stays in this status.
* `FULFILLED`: the system accepted it.
* `FULFILLED_NEEDS_FIX`: the system accepted it but reported errors in the data; review
  them and tell the user.
* `REJECTED`: the system did not accept it, so it does not count. For VeriFactu, it has
  to be sent again once the cause is fixed. For SII, BeeL. sends it again and you do not
  need to do anything: `invoice.compliance.updated` is delivered when the status changes,
  and the submission in `compliance-submissions` gives the reason in `error_code`. If the
  customer's NIF or name is not in the AEAT census, sending it again leaves the status
  in `FULFILLED_NEEDS_FIX`. If the cause is in data that only you can correct, BeeL.
  contacts you.
* `CANCELLED`: the system accepted its cancellation.

Type: `string` — one of: NOT_SUBMITTED, IN_PROGRESS, FULFILLED, FULFILLED_NEEDS_FIX, REJECTED, CANCELLED

## InvoiceComplianceSystemStatus

The status as the system itself states it, as `<system>:<CODE>` (for example
`verifactu:ACCEPTED_WITH_ERRORS`). Informational: branch on `status`, which says the same
in a vocabulary shared by every system. Null while nothing has been sent.

Type: `string`


---

Full OpenAPI spec: https://docs.beel.es/api/openapi