NewProvince is only required for addresses in Spain
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Payment Connections

Disconnect the payment provider of a NIF

Scopepayment-connections:write

Disconnects the payment connection named by {connection_id} of a company that your account owns or manages.

  • Effect: BeeL deletes the stored credentials and auto-invoicing stops at once; charges arriving afterwards are ignored and produce no invoice. Already-issued invoices are not affected.
  • The provider-side authorization is not revoked: to withdraw it, the holder must remove BeeL's access from the provider's own dashboard (in Stripe, Settings → Connected applications).
DELETE
/v1/companies/{company_id}/payment-connections/{connection_id}

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

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.

Formatuuid
connection_idstring

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.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-connections/497f6eca-6276-4993-bfeb-53cbbbba6f08"
Empty
{
  "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": "CONNECTION_NOT_FOUND",
    "message": "Payment connection not found"
  },
  "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"
  }
}

Update the payment connection settings of a NIF PATCH

Updates the auto-invoicing settings of the payment connection named by `{connection_id}` of a company your account **owns or manages**. - **Partial by field:** a field you omit keeps its current value. The series fields also accept an explicit `null`, which clears the series and falls back to the company default for that document type. `filter_config` is the exception: when sent, it **replaces the whole object**, not just the sub-fields you included — a partial `filter_config` clears every filter axis you left out. - **Read-only fields:** `id`, `provider`, `status`, `environment`, `external_account_id`, `connected_at`, `last_event_at` and `active_filters` are not part of this request and are ignored if sent. `status` moves through the disconnect operation, never here. - **Series:** each one must exist, be active, belong to this NIF and carry a compatible document type, or the request answers `422`.

List the payment events of a company's connection GET

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