NewConnections and customer replies to invoices
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Payment Connections

Update the payment connection settings of a NIF

Scopepayment-connections:write

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.
PATCH
/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

Header Parameters

Idempotency-Key?string

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx other than 503, check whether the operation took effect before retrying with a new key
  • After a 503, retry first with the same key. If the response carries Idempotency-Replay: true, the operation may have taken effect: check the resource before using a new key. Without that header, the retry runs the operation once
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Request Body

auto_invoice_enabled?boolean

Whether incoming charges are auto-invoiced.

event_source?string
Value in"PAYMENTS" | "INVOICES" | "BOTH"
auto_create_customer?boolean

Whether customers are created from the fiscal data the provider supplies.

send_invoice_by_email?boolean

Whether the auto-issued invoice is emailed to the payer.

tax_inclusive_tax?
series?

Series to number auto-issued invoices in. Omit a field to keep it, send null to clear it and fall back to the company default series for that document type.

simplificada_threshold?number

Amount in EUR up to which a charge whose buyer has no complete fiscal data (tax ID, name and address) is invoiced as a simplified invoice. Above it, the charge is not issued: it waits as a draft standard invoice until the buyer's fiscal data is completed. A buyer with complete fiscal data always gets a standard invoice, whatever the amount. Up to 400.00 is the general limit; a higher value, up to 3000.00, is the issuer's statement that its activity is one of those in article 4.2 of RD 1619/2012 (rule SIM-002). Omit to keep the current value.

Formatdouble
Range0.01 <= value <= 3000
filter_config?

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-connections/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "auto_invoice_enabled": true,    "event_source": "PAYMENTS",    "auto_create_customer": true,    "send_invoice_by_email": true,    "tax_inclusive_tax": {      "type": "IVA",      "percentage": 21,      "regime_key": "01"    },    "filter_config": {      "min_amount": 1,      "disabled_categories": [        "REFUND"      ]    }  }'
{
  "success": true,
  "data": {
    "id": "5f2b1c0e-9a3d-4c11-8f6e-7b0d2a4c9e13",
    "provider": "stripe",
    "external_account_id": "acct_1234567890",
    "external_account_name": "string",
    "environment": "PROD",
    "status": "PENDING",
    "connected_at": "2019-08-24T14:15:22Z",
    "last_event_at": "2019-08-24T14:15:22Z",
    "auto_invoice_enabled": true,
    "event_source": "PAYMENTS",
    "auto_create_customer": true,
    "send_invoice_by_email": true,
    "tax_inclusive_tax": {
      "type": "IVA",
      "percentage": 21,
      "regime_key": "01"
    },
    "series": {
      "ordinaria": "596717c6-039f-4d35-9ead-e9d2b0a927a8",
      "simplificada": "5a49dd8d-1528-46e3-8c1e-58e7c1b27d4d",
      "rectificativa": "408b5356-47cb-435e-a055-e8998fd51b68"
    },
    "simplificada_threshold": 400,
    "filter_config": {
      "min_amount": 10,
      "max_amount": 5000,
      "only_mapped_customers": true,
      "allowed_customer_ids": [
        "cus_abc123",
        "cus_def456"
      ],
      "excluded_description_patterns": [
        ".*donation.*",
        ".*tip.*"
      ],
      "required_description_patterns": [
        ".*subscription.*"
      ],
      "disabled_categories": [
        "SUBSCRIPTION"
      ]
    },
    "active_filters": [
      "amount",
      "description"
    ]
  },
  "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": "CONNECTION_NOT_FOUND",
    "message": "Payment connection not found"
  },
  "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": "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 payment connections of a NIF GET

Returns the payment provider connections of a company your account **owns or manages**, with the provider-side account each one points at and its `status`. Use it to check whether a NIF you provisioned has completed its connection. - **A NIF with no connections:** answers `200` with an empty list. - **`environment`:** Test and Live connections are independent, so only the ones living in the mode of the key you ask with are returned; this field states which. **Closed catalogue.** A NIF is not limited to one connection per provider: within a single environment it may hold several of the same provider, one per external account. What is unique is the external account itself — one live connection per provider, environment and external account. The set is still bounded and unpaginated: the collection carries no `pagination` and takes no `page`/`limit`, and every response holds the whole set for the environment of the key you ask with.

Disconnect the payment provider of a NIF DELETE

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*).