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_coverages rows (read, create, update, delete) for insurance, and a patient_billing_invoices read 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, a kind (statutory or private) and its 9-digit ik. Some private insurers have no IK, so ik is null.
  • query matches 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,
  });
}
  • kind is statutory, private or self-pay. Statutory insurance needs the insurer's insurerIk and the KVNR from the health card. Private insurance needs insurerIk, or insurerName for an insurer without an IK, plus the policy number. Self-pay needs neither.
  • checkMemberNumber runs 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.
  • order says 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 coded COVERAGE_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 });
  • update changes only the fields you send. period: null makes 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 coded COVERAGE_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.set with { plan: null } ends the running plan. It answers null when the patient had no plan to end.
  • invoices.record is keyed by identifier: recording the same identifier again updates that invoice, so a retried webhook is safe. Record a refund as status: 'cancelled' with a cancelledReason.
  • 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.retrieve fails with a not-found error coded PLAN_NOT_FOUND when the patient has no plan.
  • invoices.list pages lazily, latest first; limit sets the page size, 30 by default and at most 100.
  • accounts.retrieve(accountId) and invoices.retrieve(invoiceId) read one record. The raw FHIR resources stay readable through ovok.fhir.
  • The calls go to routes under v1/patient-billing.

See also

Last updated on

On this page