REST API guide

How to use the local API

The examples use https://billing.example.invalid, a deliberately non-routable placeholder. Replace the host and credentials with your own Billing installation.

curl --request POST https://billing.example.invalid/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_SECRET'

curl https://billing.example.invalid/api/v1/contracts?skip=0&take=20 \
  --header 'Authorization: Bearer ACCESS_TOKEN'

The local development token endpoint supports client credentials with HTTP Basic authentication or form fields. Production uses configured Keycloak client credentials and pre-bound merchant grants. Credentials belong to your Billing/Keycloak installation. See the Keycloak guide for issuer, audience and scope configuration.

Local compatibility extensions

• List endpoints preserve the source snapshot’s skip/take pattern where present.
• Use Idempotency-Key for retried mutations and If-Match with the returned ETag for supported versioned resources. A changed request under the same key returns 409; a stale revision returns 412. These are local safeguards, not universal Transform requirements.
• Use actionable JSON errors: 400 input, 401 identity, 403 grant, 404 missing resource, 409 conflict, 412 revision mismatch, 413 oversized body, 414 oversized query, 415 wrong media type, 422 business rule and 5xx server failure.
• PSP bearer fields are intentionally absent from local examples. Hosted PSP checkout/tokenization may reduce card-data handling, but it does not make PCI obligations disappear; local APIs never accept PAN or CVV.

Existing boo client map

These are observed caller mappings from the separate boo application. Consult the operation evidence below for tested requests; these mappings alone do not establish support for every historical request shape.

• GET /api/v1/billwerk/get_customer_portal_token?contract_id=... → Contracts_GetSelfServiceToken_contractId_tokenValidity_GET
• POST /api/v1/billwerk/create_contract_component_subscription → Orders_PostOrder_orderDto_POST; Orders_PostCommitOrder_id_orderCommitDto_POST
• POST /api/v1/billwerk/delete_subscription → Orders_PostOrder_orderDto_POST; Orders_PostCommitOrder_id_orderCommitDto_POST
• POST /api/v1/billwerk/create_contract_from_order; GET /api/v1/billwerk/billwerk_customer → Contracts_Get_id_GET; Customers_Get_id_GET; Customers_PutItem_id_customerDto_PUT
• Hosted order URL; provider return URL /portal/finalize.html → Hosted self-service / checkout resource; not an OpenAPI route in supplied snapshot
• GET /api/v1/billwerk/get_customer_portal_token then redirect to returned URL → Contracts_GetSelfServiceToken_contractId_tokenValidity_GET

Implementation and test evidence

No matching runtime evidence is available for this source snapshot.

Each operation separates its declared implementation status from named tests and captured response codes. Provider-dependent actions can remain unavailable even when a local handler exists. Webhook delivery and recurring billing require explicit activation; no configured payment adapter means no payment execution.