Namespaces
ovok.patientBilling
Store patients' health insurance, the plan they pay for, their billing accounts and invoices.
- Stable unknown
- Release candidate not available
- Development not available
Ovok stores a patient's health insurance, the plan they pay for, their billing accounts and their invoices as FHIR Coverage, Account and Invoice resources. ovok.patientBilling reads and writes them as flat records and checks each insurance against the insurer directory and the member-number rules. Germany is the only country supported today. The project's PATIENT_BILLING_ENABLED setting must be on; while it is off, every call fails with a permission error coded PATIENT_BILLING_DISABLED.
Turn it on
await ovok.projects.settings.update('PATIENT_BILLING_ENABLED', true);- A caller's access policy decides who may do what:
patient_billing_coveragesrows (read, create, update, delete) for insurance, and apatient_billing_invoicesread row for plans, accounts and invoices. The policy must also let the caller read the patient, or update the patient for insurance changes. - Project admins and admin client applications may do everything. Only they set plans and record invoices.
Find an insurer
const insurers = await ovok.patientBilling.insurers.list({ kind: 'statutory', query: 'tk' });- Each insurer has a
name, akind(statutoryorprivate) and its 9-digitik. Some private insurers have no IK, soikis null. querymatches part of the name or the start of the IK.
Add and change insurance
const memberNumber = 'A123456780';
if (checkMemberNumber({ country: 'DE', kind: 'statutory', value: memberNumber })) {
await ovok.patientBilling.coverages.create(patientId, {
country: 'DE',
kind: 'statutory',
insurerIk: '101575519',
memberNumber,
period: { start: '2025-01-01' },
order: 1,
});
}kindisstatutory,privateorself-pay. Statutory insurance needs the insurer'sinsurerIkand the KVNR from the health card. Private insurance needsinsurerIk, orinsurerNamefor an insurer without an IK, plus the policy number. Self-pay needs neither.checkMemberNumberruns the server's own rule offline, so a form can flag a typo at once. A KVNR must pass its check digit, ignoring spaces and case. A policy number must have 1 to 30 characters.ordersays which coverage applies first when several do: 1 is first. Two statutory coverages may not overlap in time; the second fails with a conflict error codedCOVERAGE_OVERLAP.coverages.list(patientId)returns the patient's active coverages, in order.
const [coverage] = await ovok.patientBilling.coverages.list(patientId);
await ovok.patientBilling.coverages.update(coverage.id, { order: 2 }, { ifVersion: coverage.version });updatechanges only the fields you send.period: nullmakes the coverage open-ended. A coverage's kind never changes: remove it and add another.- With
ifVersion, the change applies only while the coverage is still at the version you read. Otherwise it fails with a conflict error codedCOVERAGE_VERSION_MISMATCH. remove(coverageId)deletes the coverage. If a billing account names it, the coverage is cancelled instead, so billing history stays whole.
Plans and invoicesServer-side
await ovok.patientBilling.plans.set(patientId, {
plan: { system: 'https://example.com/plans', code: 'plus', display: 'Plus' },
period: { start: '2026-11-02T10:14:00Z', end: '2026-12-02T10:14:00Z' },
});
await ovok.patientBilling.invoices.record(patientId, {
identifier: { system: 'https://example.com/payments', value: paymentId },
status: 'balanced',
issuedAt: '2026-11-02T10:14:00Z',
lines: [{ code: { system: 'https://example.com/plans', code: 'plus' } }],
total: { value: 39, currency: 'EUR' },
});- Write these from your server, with an admin client application.
plans.setwith{ plan: null }ends the running plan. It answers null when the patient had no plan to end.invoices.recordis keyed byidentifier: recording the same identifier again updates that invoice, so a retried webhook is safe. Record a refund asstatus: 'cancelled'with acancelledReason.- An invoice belongs to the patient's billing account, which Ovok creates if it is missing.
Read plans, accounts and invoices
const plan = await ovok.patientBilling.plans.retrieve(patientId);
const accounts = await ovok.patientBilling.accounts.list(patientId);
for await (const invoice of ovok.patientBilling.invoices.list(patientId)) {
console.log(invoice.issuedAt, invoice.status, invoice.total);
}plans.retrievefails with a not-found error codedPLAN_NOT_FOUNDwhen the patient has no plan.invoices.listpages lazily, latest first;limitsets the page size, 30 by default and at most 100.accounts.retrieve(accountId)andinvoices.retrieve(invoiceId)read one record. The raw FHIR resources stay readable throughovok.fhir.- The calls go to routes under
v1/patient-billing.
See also
- patientBilling API reference: every method and type.
- ovok.projects for project settings.
- Errors and retries
Last updated on