{
  "resourceType": "OperationDefinition",
  "id": "billing-launch",
  "url": "https://fhir.apps.health/OperationDefinition/billing-launch",
  "title": "Billing launch",
  "description": "Open a signed-in ClinicAid session for a clinic, optionally prefilled from one appointment, and\nreturn the single-use address to send the person to.\n\n    POST [base]/$billing-launch\n\n**This is a handoff, not a billing operation.** No claim is created here, no money moves, and\nnothing is adjudicated. The reply is a URL. What happens after a person follows it is ClinicAid's,\nand this endpoint learns of it only later and only in outline: a separate read-back records that\nthe appointment was invoiced, as a timestamp on the\n[`appointment-invoiced`](StructureDefinition-appointment-invoiced.md) extension. **No `Invoice`\nresource is written by this operation.** For fee codes, amounts or claim status, ask ClinicAid.\n\n**`affectsState` is `true`.** The launch spends a clinic's ClinicAid credential and mints a\nsingle-use signed-in address, so it is a `POST` and is neither cacheable nor safe to repeat\nspeculatively. Repeating one in flight is refused as `launchInProgress` rather than opening a\nsecond session.\n\n### The destination decides the shape of the request\n\n[`destination`](ValueSet-nexus-billing-launch-destination.md) names which ClinicAid screen opens,\nand it governs two other parameters:\n\n| destination | `appointment` | `item` |\n|---|---|---|\n| `appointmentInvoice` (the default) | **required** | admitted, repeatable |\n| every other destination | **refused** | **refused** |\n\nA listing sent an `appointment` or an `item` is **refused, not quietly ignored** -- dropping either\nwould open a screen the caller did not ask for, or bill a line it did not send. Omitting\n`destination` entirely reads as `appointmentInvoice`, which is what keeps a caller written before\ndestinations existed meaning what it always meant.\n\n### Two shapes for a billing item\n\nAn item may be sent as a nested `item` part carrying its three sub-parts, which is the shape to\nwrite against. The three sub-part names are ALSO read at the top level as a **legacy single-item\nshape**, still accepted for callers written before `item` existed. The legacy shape carries at most\none item. Do not mix them.\n\nA legacy body carrying `billedUnits` or `diagnosticCode` with no `healthServiceCode` cannot be read\nas an item at all; it is forwarded to the service as sent rather than dropped, so the service's own\nvalidator refuses it loudly instead of this gateway silently unsaying what the caller submitted.\n\n### Reading the reply\n\nA reply is published **only when the launch launched**, so `status` has exactly one value,\n`launched`, and `launchUrl` is present exactly then.\n\nEvery other ending is an\n[`OperationOutcome`](https://hl7.org/fhir/R4/operationoutcome.html) under the HTTP status its\nreading gives it, carrying the refusal reason as a coding on `issue.details` from the\n[Billing Launch Refusal Reason](ValueSet-nexus-billing-launch-refusal.md) set. **Match on that\ncoding, never on the advisory sentence beside it**: the sentence is developer-facing, is not a\ntranslation of the code, and is not stable. Tolerate a reason this guide does not list -- the\nplatform and this guide ship on different cadences, and a launch refused for an unrecognised reason\nis still refused.\n\nAsking for a launch requires the billing-launch permission. A caller without it is refused before\nany gate that would name a reason, so that outcome carries no refusal coding.",
  "name": "BillingLaunch",
  "status": "draft",
  "kind": "operation",
  "experimental": false,
  "publisher": "WELLSTAR Technologies Corp.",
  "affectsState": true,
  "code": "billing-launch",
  "system": true,
  "type": false,
  "instance": false,
  "parameter": [
    {
      "name": "clinicId",
      "use": "in",
      "min": 1,
      "max": "1",
      "type": "string",
      "documentation": "The clinic whose ClinicAid account the launch spends. A string that must parse as a UUID; a value that does not parse is refused. Required for every destination."
    },
    {
      "name": "destination",
      "use": "in",
      "min": 0,
      "max": "1",
      "type": "code",
      "documentation": "Which ClinicAid screen to open. Omitted reads as `appointmentInvoice`. Echoed on the reply. A word outside the value set names no routable screen and is refused.",
      "binding": {
        "strength": "required",
        "valueSet": "https://fhir.apps.health/ValueSet/nexus-billing-launch-destination"
      }
    },
    {
      "name": "appointment",
      "use": "in",
      "min": 0,
      "max": "1",
      "type": "Reference",
      "targetProfile": [
        "https://fhir.apps.health/StructureDefinition/nexus-emr-core-appointment"
      ],
      "documentation": "The appointment to bill, as a literal relative reference of the form `Appointment/{id}`. REQUIRED when the destination is `appointmentInvoice` and REFUSED for every other destination. It must be a `Reference`: a plain string carrying the same text is not read, and a contained resource is refused rather than dropped."
    },
    {
      "name": "item",
      "use": "in",
      "min": 0,
      "max": "*",
      "documentation": "One billing item, prefilling one invoice line. Repeatable, and admitted only by the `appointmentInvoice` destination. An item whose `healthServiceCode` is absent cannot be built and is refused by the service rather than dropped here.",
      "part": [
        {
          "name": "healthServiceCode",
          "use": "in",
          "min": 1,
          "max": "1",
          "type": "string",
          "documentation": "The item's service code, as the vendor spells it. An empty code is forwarded as sent, because the service decides what an empty code means."
        },
        {
          "name": "billedUnits",
          "use": "in",
          "min": 0,
          "max": "1",
          "type": "integer",
          "documentation": "The item's units."
        },
        {
          "name": "diagnosticCode",
          "use": "in",
          "min": 0,
          "max": "1",
          "type": "string",
          "documentation": "The item's diagnostic code, forwarded to the vendor exactly as sent. UNBOUND AND UNTYPED ON PURPOSE: the vendor owns the rule that judges it. In Ontario this is a code from the provincial diagnostic set described by `on-ohip-diagnostic-codes`, which is ICD-9-like in shape and is NOT ICD-9 -- see that system before deriving one."
        }
      ]
    },
    {
      "name": "healthServiceCode",
      "use": "in",
      "min": 0,
      "max": "1",
      "type": "string",
      "documentation": "LEGACY single-item shape, read at the top level for callers written before `item` existed. Prefer the `item` part. Do not send both shapes."
    },
    {
      "name": "billedUnits",
      "use": "in",
      "min": 0,
      "max": "1",
      "type": "integer",
      "documentation": "LEGACY single-item shape. Prefer the `item` part."
    },
    {
      "name": "diagnosticCode",
      "use": "in",
      "min": 0,
      "max": "1",
      "type": "string",
      "documentation": "LEGACY single-item shape. Prefer the `item` part. See the note on the nested `diagnosticCode`: it is unbound for the same reason."
    },
    {
      "name": "status",
      "use": "out",
      "min": 1,
      "max": "1",
      "type": "string",
      "documentation": "What became of the launch. A reply is published only when the launch launched, so the only value is `launched`. Every other ending is an OperationOutcome, not a reply. Sent as a STRING, not a code: every part of this reply is published as a string except `destination`, and a strict parser looking for `valueCode` here will find nothing."
    },
    {
      "name": "destination",
      "use": "out",
      "min": 1,
      "max": "1",
      "type": "code",
      "binding": {
        "strength": "required",
        "valueSet": "https://fhir.apps.health/ValueSet/nexus-billing-launch-destination"
      },
      "documentation": "The destination that was opened, echoed back. Always present, and always resolved: a request that named none is answered with `appointmentInvoice`, so the reply says which screen was opened rather than repeating the caller's silence. This is the one part of the reply sent as a `code` rather than a string, because it is a bounded vocabulary this specification publishes."
    },
    {
      "name": "launchUrl",
      "use": "out",
      "min": 1,
      "max": "1",
      "type": "string",
      "documentation": "The single-use signed-in address to send the person to. Always present on a reply, because a reply is only published when the launch launched. Treat it as a credential: single-use, and not to be logged, stored or shared. Sent as a STRING rather than a `url` deliberately -- it is opaque, and it must be opened exactly as minted rather than normalised."
    },
    {
      "name": "appointment",
      "use": "out",
      "min": 0,
      "max": "1",
      "type": "Reference",
      "targetProfile": [
        "https://fhir.apps.health/StructureDefinition/nexus-emr-core-appointment"
      ],
      "documentation": "The appointment the launch was opened for, echoed back. Present exactly when the destination carries one, which today means `appointmentInvoice` alone -- so its ABSENCE is meaningful and is not an omission: it says the screen opened has no subject."
    },
    {
      "name": "message",
      "use": "out",
      "min": 1,
      "max": "1",
      "type": "string",
      "documentation": "Display words a caller may show."
    }
  ]
}