Patient billing

Get an invoice

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
GET
/v1/patient-billing/invoices/{invoiceId}

Gets one invoice.

Scope: the caller's project, with PATIENT_BILLING_ENABLED on.

Behaviour

  • Your access policy must grant patient_billing_invoices read and let you read the invoice's patient. An invoice you cannot see answers 404 INVOICE_NOT_FOUND.
  • An invoice issued from charges names its clinicId, and each line its chargeId and amount. A recorded payment has neither.

Example

curl 'https://api.sandbox.ovok.com/v1/patient-billing/invoices/<invoiceId>' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

invoiceId*string

The invoice id.

Match^[A-Za-z0-9\-.]{1,64}$

Response Body

The invoice.

application/json
  1. response
id*string
version*string

Send it as If-Match: W/"<version>" to change only this version.

patientId*string
identifier*
status*string
cancelledReason*string
issuedAt*string
accountId*string
clinicId*string

The clinic that issued it from charges; null for a recorded payment.

lines*array<>
total*
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/patient-billing/invoices/string'
Example Response
{  "id": "string",  "version": "string",  "patientId": "string",  "identifier": {    "system": "string",    "value": "string"  },  "status": "string",  "cancelledReason": "string",  "issuedAt": "string",  "accountId": "string",  "clinicId": "string",  "lines": [    {      "code": {        "system": "string",        "code": "string",        "display": "string"      },      "chargeId": "string",      "amount": {        "value": 0,        "currency": "string"      }    }  ],  "total": {    "value": 0,    "currency": "string"  }}

Issue an invoice from charges POST

Issues an invoice of the patient's billable charges at one clinic, for example a private GOÄ bill. The invoice is a FHIR `Invoice` from the clinic to the patient, a line per charge with its price; the charges turn `billed` in the same commit. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_invoices` `create` and let you read the patient, else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `PATIENT_BILLING_PATIENT_NOT_FOUND`. The invoice shows the charges it bills, so this row reads them too. - `clinicId` must be a clinic the patient is enrolled with, else **422** `BILLING_CLINIC_INVALID`. - `chargeIds` names the charges to bill; left out, every billable charge at the clinic is billed, 49 at most (**422** `CHARGES_TOO_MANY`). A charge named that is not billable there answers **409** `CHARGE_NOT_BILLABLE`; nothing billable at all, **409** `NO_BILLABLE_CHARGES`. - The charges must share one currency, else **422** `CHARGE_CURRENCY_MIXED`. - `identifier`, such as your invoice number, is optional. With it, the same identifier for the same patient again answers the invoice already issued, with **200**. A new invoice answers **201** with `Location: /v1/patient-billing/invoices/<id>`. - Changes to one patient's charges run one at a time: another still running, or a charge changed while billing, answers **409**; send yours again. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/invoices/issue' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "identifier": { "system": "https://example.com/invoice-numbers", "value": "2026-000123" }, "clinicId": "<clinicId>", "chargeIds": null, "issuedAt": null }' ```

List prices GET

Lists the project's price list, a page at a time: one price per code, each a FHIR `ChargeItemDefinition` with its unit price and the period it applies in. **Scope:** any member of the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Only prices on the list are listed; a removed price is retired and left out. - `code=<system>|<code>` answers only that code's price. - `limit` is 1 to 100 (30 when left out). Send `nextCursor` back as `cursor` for the next page; a cursor no page gave answers **400** `PATIENT_BILLING_CURSOR_INVALID`. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/prices?code=http://fhir.de/CodeSystem/kbv/ebm|03040' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```