Download the PHP package beckonbilling/api-client without Composer

Beckon Billing API client (PHP)

The official PHP client for the Beckon Billing REST API (v1) - a small, typed, idiomatic wrapper over the public /api/v1 surface: customers, article categories, articles, quotes, orders, outbound invoices and recurring invoices, the read-only units and document-templates vocabularies, plus user-token authentication.

• PSR-4 / PHP >=8.2, no framework required.
• Bring your own HTTP client - any PSR-18 client works and is auto-discovered.
• Typed exceptions you can branch on with a stable error.key.
• The canonical API contract lives in openapi.yaml (import it into Postman/Insomnia). Building AI tooling on top? See AGENTS.md.

This is a thin, open-source HTTP wrapper - it holds no secrets and no server code. You still need a valid API token to do anything.

Installation

You also need any PSR-18 HTTP client + PSR-17 factories. If you don't already have one, add Guzzle (auto-discovered):

Quick start

Authentication

Every request sends Authorization: Bearer <token>. There are two token flavours - both authorise through the same per-feature model:

Organisation tokens

Created in the portal under Firma -> API-Zugriff. Bound to one organisation; carry an explicit permission grant + the send/bank capabilities. Pass the bbp_... token as token.

User tokens (app sign-in)

Mint a token from email + password - no portal visit:

If two-factor authentication is enabled, login() throws an AuthenticationException whose getErrorKey() is tfa_required until you pass a code:

Organisation scoping

Set a default organisation in the config, or override per call:

A user token with exactly one organisation may omit it entirely.

Resources

Each writable resource offers list(), autoPaging(), get(), create(), update(), delete(). Quotes and invoices add lifecycle actions (issue, send/cancel, setPaid, pdf); articles add variants. units and documentTemplates are read-only - list(), autoPaging(), get().

Quotes::convert() is deprecated: POST /quotes/{id}/convert was retired on 2026-08-28 and now answers 410 on every call, so the method throws a local GoneException (quote_conversion_moved) instead of making a request. A won quote becomes an order, and the order is what gets invoiced - see AGENTS.md for what that means for this client today.

Deprecations

recurring_invoice.document_ids - the attachment list carried as internal INTEGER ids, the one place this API ever exposed them - is deprecated as of the next minor release and removed in the next major release. Use document_uuids, the same attachments addressed by uuid:

Nothing on the wire changes while both exist: the API keeps emitting and accepting either key, and a request carrying both is applied from document_uuids. Move anyway - an integer id belonging to another organisation, or to nothing at all, is dropped in silence rather than refused, so a wrong value cannot be told apart from a saved one.

Pagination

Lists return a Collection (data, total, limit, offset; iterable and countable):

Or iterate everything lazily:

Error handling

Non-2xx responses throw a typed exception. Every one exposes getStatusCode(), getErrorKey() (the stable slug) and getResponse().

All extend ApiException, so a single catch (ApiException $e) covers everything.

Custom HTTP client

Inject any PSR-18 client / PSR-17 factories (for a preconfigured Guzzle, retries, proxies, timeouts, test doubles ...):

Working models

Resource objects wrap the JSON payload: read documented fields as properties or array keys, and any field the API adds later stays reachable without a client upgrade.

Contributing / development

The API contract in openapi.yaml and the agent guide in AGENTS.md are part of the release and are kept in sync with the API surface. The reasoning behind them lives in docs/decisions/ as ADRs; a change that affects more than one file, or that a consumer would notice, gets one.

License

MIT - see LICENSE.