NewTell a voided invoice from a totally rectified one, without a second call
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Payment Connections

Open an authorization to connect a payment provider

Scopepayment-connections:write

Opens an authorization session so the holder of a NIF (company) your platform manages can connect a payment provider (stripe), white-label by API.

Returns an authorization_url where the holder authorizes the connection. After authorization, BeeL's callback finalizes the connection and redirects back to the return_url of your portal (if provided) with rich params (see return_url). The connection itself is created only once the holder authorizes, so it appears in GET /v1/companies/{company_id}/payment-connections afterwards, not before — which is why this is a sibling sub-resource and not a POST on the collection.

The connection is sealed under the NIF's holder, so the auto-invoicing runs under the correct NIF.

The NIF must be activated in the mode of your API key (beel_sk_test_* → Test, beel_sk_live_* → Live). Opening an authorization on a NIF that is not activated in that mode returns 400 with code COMPANY_NOT_ACTIVATED_IN_ENVIRONMENT and no authorization_url: activation is what creates the invoice series and tax configuration, so without it every incoming charge would be skipped instead of invoiced. Test and Live activations are independent — a NIF live in one mode still needs activating in the other.

POST
/v1/companies/{company_id}/payment-connections/authorizations

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

Obtaining Keys: API Keys are managed from the BeeL dashboard

Security: API Keys are secret credentials. Do not share them or store them in source code

In: header

Path Parameters

company_idstring

NIF (company) the authorization is opened for. 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 NIF you do not reach answers 403, and so does a NIF 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)
  • If the same key is sent twice, the result of the first operation is returned
  • Keys 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 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

providerstring

Payment provider slug in lowercase. Currently only stripe (Stripe Connect) is operative; woocommerce and shopify are reserved for future providers. Any other value answers 422.

return_url?string

URL of your portal to redirect the account holder back to after the OAuth callback completes. Must be an absolute https:// URL. On success BeeL appends status=success, provider (slug), company_id, connection_id and account (the provider account id, e.g. acct_...). On error it appends status=error, provider and message (an error code). When omitted, or when the URL is not a valid absolute https:// URL, the callback redirects to BeeL's default integrations screen.

Match^https://.*

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-connections/authorizations" \  -H "Content-Type: application/json" \  -d '{    "provider": "stripe"  }'
{
  "success": true,
  "data": {
    "authorization_url": "http://example.com"
  },
  "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": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "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": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Data cannot be processed",
    "details": {
      "field": "Specific error description"
    }
  },
  "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"
  }
}

Cancel representation DELETE

**Deprecated.** Use `DELETE /v1/companies/{company_id}/representation`, which behaves identically. This route keeps working until the date announced in its `Sunset` response header. Cancels the current representation process.

List a NIF's payment connections GET

Lists the payment provider connections of a NIF (company) that your account **owns or manages**. Use it to check whether a NIF you provisioned has completed its connection.