# List the payment events of a company's connection API Reference Lists the payment events received through the payment provider connection of a NIF (company), most recent first. Use it to audit the charges that produced an invoice and to find the ones that did not. - **By default, every event is listed.** Nothing is hidden: events the connection skipped, duplicates and disputes are all returned. Narrow the list with the filters below; what you do not filter, you get. Set `charges_only=true` to read the same events as one row per money movement instead. - **Scope:** events belong to the connection, not to the NIF directly. The `{connection_id}` segment picks one connection of the NIF in the path, and only the events of that connection are returned; an event of another NIF of the same account is never reachable from here. - **Unknown connection:** a `{connection_id}` that belongs to no connection of this NIF returns `404`. ## GET /v1/companies/{company_id}/payment-connections/{connection_id}/events **List the payment events of a company's connection** Lists the payment events received through the payment provider connection of a NIF (company), most recent first. Use it to audit the charges that produced an invoice and to find the ones that did not. - **By default, every event is listed.** Nothing is hidden: events the connection skipped, duplicates and disputes are all returned. Narrow the list with the filters below; what you do not filter, you get. Set `charges_only=true` to read the same events as one row per money movement instead. - **Scope:** events belong to the connection, not to the NIF directly. The `{connection_id}` segment picks one connection of the NIF in the path, and only the events of that connection are returned; an event of another NIF of the same account is never reachable from here. - **Unknown connection:** a `{connection_id}` that belongs to no connection of this NIF returns `404`. ### 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 events belong to — 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. - **connection_id** (required) in path `string`: Unique identifier (UUID) of the payment connection the operation acts on, as returned by `GET /v1/companies/{company_id}/payment-connections`. A NIF can hold several connections of the same provider, so the provider slug alone does not name one. A connection of another NIF answers `404`, exactly like one that does not exist. - **page** (optional) in query `integer` (default: 1): Page number, starting at 1. The response echoes it back as `pagination.current_page`. - **limit** (optional) in query `integer` (default: 20): How many items to return per page. The response echoes it back as `pagination.items_per_page`. - **status** (optional) in query `array`: Keep only the events in these processing states. Repeat the parameter to combine states; omit it, or send it empty (`status=`), for all of them. - **failure_reason** (optional) in query `array`: Keep only the events that did not complete for these reasons. Repeat the parameter to combine reasons. An empty value (`failure_reason=`) is the same as omitting it. - **failure_category** (optional) in query `array`: Keep only the events that did not complete for a cause in these categories. Repeat the parameter to combine categories. Events that completed carry no category and are therefore never kept by this filter. An empty value (`failure_category=`) is the same as omitting it. - **event_kind** (optional) in query `array`: Keep only the events of these kinds. Matches `event_kind`, never `event_type`: the kind is what the event is about, while `event_type` is the raw name the provider emitted (`payment_intent.succeeded`) and is not filterable. `UNKNOWN` keeps every event whose provider name we do not classify. Repeat the parameter to combine kinds. An empty value (`event_kind=`) is the same as omitting it. - **min_amount** (optional) in query `number`: Keep only the events whose `amount` is at or above this value. - **max_amount** (optional) in query `number`: Keep only the events whose `amount` is at or below this value. - **needs_action** (optional) in query `boolean`: `true` keeps only the events still worth acting on; `false`, only the ones that are not. Omit it for both. - **from** (optional) in query `string`: Keep only the events received at or after this instant. - **to** (optional) in query `string`: Keep only the events received at or before this instant. - **q** (optional) in query `string`: Free-text search over the payer name and the provider identifiers of the charge (`pi_`, `ch_`, `cs_`, `evt_`). Case-insensitive, partial matches allowed. The payer email is deliberately not searchable. - **include_discarded** (optional) in query `boolean` (default: false): Include the events you discarded. They are excluded by default; discarding is a decision about the list, not a state of the event. - **charges_only** (optional) in query `boolean` (default: false): Return one row per money movement instead of one row per event. Today, when this parameter is omitted or `false`, every event is listed. **The default changes on 11 December 2026.** From that day, omitting this parameter reads the listing as `charges_only=true` — one row per money movement. Until then a request that omits it answers with `Deprecation`, `Sunset` and `Link` headers. Send the value you want explicitly, whichever it is, so the change of default cannot surprise you. See the [migration guide](https://docs.beel.es/changelog/payments-cleanup). A money movement is a sale, a failed payment, each refund and each dispute. The provider usually reports a single movement through several events. When this parameter is `true`, each movement is returned in at most two rows: its outcome and, when any of its events requires action, its incident. The outcome row stands for the events of the movement that require no action; the incident row stands for the events of the movement that require action, so an invoiced movement that still has something to resolve always shows it. Within each row, the event that produced an invoice comes first, then an event of a classified kind before an unclassified one, and then the most recent one. A sale and a failed payment of the same charge are two movements, and every refund and every dispute of a charge is a movement of its own; the opening and the closing of a dispute are the same movement. An event of an unclassified kind that requires action joins the incident row of the movement its identifier names: a charge joins its sale, a dispute joins that dispute, and a refund or a credit note joins that refund. An event whose identifier names no movement, or that carries no identifier at all, stays a row of its own and is never merged with another. Events that moved no money, such as a customer, a price or a product being created, are left out, except those that require action, which are always listed. Discarded events of a movement that is still listed through a live event are ignored: they are neither returned nor counted. A movement whose events are all discarded is returned as a single row, only when `include_discarded` is `true`, and counts once in `discarded`. Without other filters, the number of rows returned with `include_discarded=true` is therefore `total` plus `discarded`. The other filters narrow the rows returned and `pagination.total_items`, and nothing else. `counts` describes the whole connection in the view you asked for and disregards every other filter: with `charges_only=true`, its `total`, `discarded`, `needs_action` and `by_status` values count money movements rather than individual events, while its `ignored` and `failure_reasons` values keep counting events. A request that filters by `q` may therefore return a single row while `counts.total` still reports every movement of the connection. ### Responses #### 200: Payment events of the connection **Content `application/json`:** - **success** `boolean`: No description - **data** `object`: No description - **events** (required) `array[ManagedPaymentEvent]`: No description - **pagination** `Pagination` - **counts** `PaymentEventCounts`: How the events of the connection break down, over the whole connection and not just the page you are reading. The filters of the request (`q`, `status`, `needs_action`, dates, amounts and the rest) do not narrow these counts, which may therefore exceed `pagination.total_items`: they are what lets you show "12 need action" without asking for every page. Only two parameters have a bearing on them: `charges_only` changes what is counted (money movements instead of events), and `include_discarded` decides whether discarded events take part in `by_status` and `failure_reasons`. - **meta** `ResponseMeta` #### 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. **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. The same answer is given for a NIF that does not exist. **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: `CONNECTION_NOT_FOUND` — no connection of this NIF carries this `{connection_id}`. It speaks of the connection, never of the NIF: a NIF you cannot reach answers `403`, while a connection of another NIF answers this same `404` so that naming it reveals nothing. **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": "CONNECTION_NOT_FOUND", "message": "Payment connection not found" }, "meta": { "timestamp": "2025-01-15T10:30:00Z", "request_id": "4bf92f3577b34da6a3ce929d0e0e4736" } } ``` #### 422: The request cannot be answered as written: - `EVENT_FILTER_RANGE_INVALID`: a range came inverted — `min_amount` above `max_amount`, or `from` after `to`. Both ends are inclusive, so equal values are fine. The range is rejected rather than applied because an inverted one matches nothing, and an empty list would be indistinguishable from having no events. **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") #### 429: Rate limit exceeded **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 `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 ## ListManagedPaymentEventsResponse - **success** `boolean`: No description - **data** `object`: No description - **events** (required) `array[ManagedPaymentEvent]`: No description - **pagination** `Pagination` - **counts** `PaymentEventCounts`: How the events of the connection break down, over the whole connection and not just the page you are reading. The filters of the request (`q`, `status`, `needs_action`, dates, amounts and the rest) do not narrow these counts, which may therefore exceed `pagination.total_items`: they are what lets you show "12 need action" without asking for every page. Only two parameters have a bearing on them: `charges_only` changes what is counted (money movements instead of events), and `include_discarded` decides whether discarded events take part in `by_status` and `failure_reasons`. - **meta** `ResponseMeta` ## ManagedPaymentEvent A payment event of a managed NIF's connection (curated subset). - **id** (required) `string` (uuid): Identifier of the payment event. - **provider** (required) `string`: Payment provider slug (lowercase). (example: "stripe") - **event_type** (required) `string`: Raw event name as the provider emitted it. Preserved verbatim so you can trace the event back on the provider's side. Not filterable — filter by `event_kind`. (example: "payment_intent.succeeded") - **event_kind** (required): What the event is about, once `event_type` has been classified. This is the value the `event_kind` filter takes, so what you read here you can ask for again. (example: "PAYMENT_COMPLETED") - **external_event_id** (required) `string`: Provider-side event identifier. (example: "evt_1234567890") - **external_payment_id** `string`: Canonical identity of the payment at the provider. On Stripe this is always the PaymentIntent id (`pi_…`), so every event of the same payment carries the same value and can be grouped by it. Null while the identity is not yet resolved. To trace the event back to the object that delivered it, use `source_object_id`. (example: "pi_1234567890") - **source_object_id** `string`: Provider object that delivered this event (`in_…`, `cs_…`, `ch_…`, `pi_…`). Use it to open the originating invoice, checkout session or charge at the provider. It is an audit trail only: it never identifies the payment — `external_payment_id` does. (example: "in_1234567890") - **currency** `string`: ISO 4217 currency of the event. Absent on an event that moves no money — a failed intent, or a provider notice we do not classify — and then `amount` is absent too. (example: "EUR") - **amount** `number`: Amount the event carries. Absent whenever `currency` is: the two travel together, so an amount never arrives without the currency that gives it meaning. (example: 150) - **fee_amount** `number`: Provider fee, when reported. - **net_amount** `number`: Amount net of the provider fee, when reported. - **category**: Which product line the money came from, resolved when the event was processed. Not the same as `event_kind`: that one says what happened, this one says where it came from. `null` when the event does not fall in any category, or when it predates the field. - **money_returned** `boolean`: Whether money actually went back to the payer through the provider. Always `true` for a refund. For a credit note it is `true` only when the note settles provider refunds: a note credited against an unpaid invoice, or settled outside the provider, corrects the same amount without moving any money. `null` when the concept does not apply, as on a charge. - **customer_email** `string`: Payer email reported by the provider. - **customer_name** `string`: Payer name reported by the provider. - **status** (required) `PaymentEventStatus`: Processing status of a payment event. - RECEIVED: queued, awaiting processing - PROCESSING: in flight - PROCESSED: invoice was created (`invoice_id` is set) - FAILED: processing failed (see failure_reason / failure_message) - SKIPPED: filtered out by user rules (see skip_reason) - MANUALLY_RESOLVED: operator marked it as resolved outside BeeL — terminal - **invoice_id** `string` (uuid): Invoice generated from the event, when there is one. - **invoice_number** `string`: Number of the invoice generated from the event. `null` while that invoice is still a draft — a draft has no number yet — and `null` when the event produced no invoice. (example: "2026/0042") - **failure_category**: High-level cause of the failure, when the event did not complete. Same vocabulary the `failure_category` filter takes. - **failure_reason** `string`: Stable failure code you can branch on. (example: "MISSING_DEFAULT_SERIES") - **failure_message** `string`: Readable explanation of the failure, in the language of the request. - **needs_action** (required) `boolean`: Whether the event did not complete and is still worth acting on. Events that failed for reasons outside your control are excluded. - **draft_available** (required) `boolean`: Whether a draft invoice can be generated from this event. When `false`, the draft operation would be rejected. - **retry_available** (required) `boolean`: Whether retrying this event would be accepted right now. Do not derive it from `status`: a skipped event may still be recoverable, and a failed one with no retries left is not. - **discard_available** (required) `boolean`: Whether this event can be discarded — taken out of the list. When `false`, the discard operation would be rejected. An event that is `PROCESSED` or `PROCESSING` cannot be discarded: it has (or is about to have) an invoice that already went through VeriFactu, and hiding it would break the audit trail. Do not derive it from `status`: read this flag. Already-discarded events keep the flag they would have — what applies to them is restore, not discard. - **retry_count** (required) `integer`: Retries charged to the event: those that ended in an outcome attributable to it. A retry that failed for a transient cause outside the event is not counted. - **received_at** (required) `string` (date-time): When the event was received. - **processed_at** `string` (date-time): When processing of the event finished. - **description** `string`: Charge description as the provider reported it. It is what the description filters of the connection match against, so it is what makes them auditable. - **payment_method**: How the charge was paid, when the provider reported it. `null` means the provider did not report a method for this event. (example: "CARD") - **discarded** (required) `boolean`: Whether the event was discarded (soft-deleted) and is hidden by default. - **discarded_at** `string` (date-time): When the event was discarded, when it is. ## Pagination - **current_page** (required) `integer`: No description (example: 1) - **total_pages** (required) `integer`: How many pages the query has. An empty collection has **one** page — the first one, empty — so the smallest value a canonical route returns is `1`. The deprecated flat aliases (`/v1/invoices`, `/v1/customers`, …) answer `0` for that same empty collection, and `has_next`/`has_previous` follow suit. They were left as they were on purpose: a client that reads `total_pages == 0` as "no results" would break if it changed under it. Do not compare the two families of routes field by field; read `total_items` if what you want to know is whether anything came back. (example: 5) - **total_items** (required) `integer`: No description (example: 87) - **items_per_page** (required) `integer`: No description (example: 20) - **has_next** `boolean`: No description - **has_previous** `boolean`: No description ## PaymentEventCounts How the events of the connection break down, over the whole connection and not just the page you are reading. The filters of the request (`q`, `status`, `needs_action`, dates, amounts and the rest) do not narrow these counts, which may therefore exceed `pagination.total_items`: they are what lets you show "12 need action" without asking for every page. Only two parameters have a bearing on them: `charges_only` changes what is counted (money movements instead of events), and `include_discarded` decides whether discarded events take part in `by_status` and `failure_reasons`. - **total** (required) `integer`: Events of the connection that are not discarded — the size of the list you get when you filter by nothing. (example: 183) - **discarded** (required) `integer`: Events you discarded. They are not part of `total`; ask for them with `include_discarded=true`. (example: 7) - **needs_action** (required) `integer`: Events that are waiting for you to do something — the same set you get with `needs_action=true`. Counts only events that are not discarded, so it is part of `total`. **Deprecated. Retires on 11 December 2026.** Filter with `needs_action=true` and read `pagination.total_items` instead. See the [migration guide](https://docs.beel.es/changelog/payments-cleanup). (example: 12) - **ignored** (required) `integer`: Events that were skipped on purpose and need nothing from you (duplicates, your own filters, event types that are not invoiced). Counts only events that are not discarded, so it is part of `total`. **Deprecated. Retires on 11 December 2026.** The closest surviving figure is `by_status.SKIPPED`. See the [migration guide](https://docs.beel.es/changelog/payments-cleanup). (example: 31) - **by_status** (required) `object`: Number of events per processing status. (example: {"PROCESSED":148,"SKIPPED":31,"FAILED":4}) - **by_failure_reason** (required) `object`: Number of events per failure reason, among those that did not complete. Events that completed do not appear here. **Deprecated. Retires on 11 December 2026.** Use `failure_reasons`, which carries the same counts plus the reason written out for a person. See the [migration guide](https://docs.beel.es/changelog/payments-cleanup). (example: {"EVENT_IGNORED_BY_DESIGN":25,"MISSING_DEFAULT_SERIES":4}) - **failure_reasons** (required) `array[PaymentEventFailureReasonCount]`: Number of events per failure reason, among those that did not complete, with the reason already written out in the language of the request. Events that completed do not appear here. Replaces the deprecated `by_failure_reason`. ## ResponseMeta - **timestamp** `string` (date-time): No description (example: "2025-01-15T10:30:00Z") - **request_id** `string`: No description (example: "4bf92f3577b34da6a3ce929d0e0e4736") ## 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"}) ## PaymentEventStatus Processing status of a payment event. - RECEIVED: queued, awaiting processing - PROCESSING: in flight - PROCESSED: invoice was created (`invoice_id` is set) - FAILED: processing failed (see failure_reason / failure_message) - SKIPPED: filtered out by user rules (see skip_reason) - MANUALLY_RESOLVED: operator marked it as resolved outside BeeL — terminal Type: `string` — one of: RECEIVED, PROCESSING, PROCESSED, FAILED, SKIPPED, MANUALLY_RESOLVED ## PaymentEventFailureReasonCount How many events share one failure reason. - **code** (required) `string`: Stable identifier of the reason. Branch on this, not on `label`. (example: "MISSING_DEFAULT_SERIES") - **label** (required) `string`: The reason written out for a person, in the language of the request. (example: "No hay serie predeterminada configurada") - **count** (required) `integer`: Events of the connection with this reason. (example: 4) --- Full OpenAPI spec: https://docs.beel.es/api/openapi