Skip to main content

updateInvoice — record external Healthcode submission outcomes

Summary​

The updateInvoice mutation now accepts an optional healthcode block on UpdateInvoiceDataInput, so integrators who submit claims to Healthcode outside Semble can write submission outcomes back to the invoice.

  • updateInvoice(invoiceData: { healthcode: … }) — record Healthcode submission state on an existing invoice.
  • UpdateInvoiceHealthcodeInput — optional status (String) and/or providerReference (String).
  • INVOICE_INTEGRATIONS_HEALTHCODE_STATUS_UPDATED webhook — fired when Healthcode fields change via this mutation (in addition to the existing INVOICE_UPDATED webhook on any invoice update).

Validation rules:

  • status — optional; when provided, must be one of the Healthcode bill status values Semble stores internally (for example Unprocessed, In-process, Validated, Collected).
  • providerReference — optional; maximum 25 characters (same constraint as internal Healthcode submission).
  • When healthcode is present, at least one of status or providerReference is required.

Partial updates merge with any existing Healthcode data on the invoice. updateAttempts is not exposed or modified via the API (reserved for internal status polling). updatedAt is set server-side when Healthcode fields change.

This release is additive: existing updateInvoice calls that only send date, doctorId, locationId, comments, or extraInfo behave as before.

Out of scope for this release: reading Healthcode fields on Invoice via the public API, submitInvoiceToHealthcode, and triggering Healthcode status polling from Healthcode's API.

Integration guidance​

  • First-time external submission: Call updateInvoice with healthcode.status and/or healthcode.providerReference on an invoice that has no existing Healthcode object.
  • Status updates: Send only healthcode.status to update status while preserving an existing providerReference.
  • Reference updates: Send only healthcode.providerReference to update the sender reference while preserving an existing status.
  • Webhooks: Subscribe to INVOICE_INTEGRATIONS_HEALTHCODE_STATUS_UPDATED if you need to react when partner-recorded Healthcode state changes. INVOICE_UPDATED still fires for all invoice updates, including Healthcode-only updates.
  • Validation errors: Invalid status values and providerReference longer than 25 characters return error in the mutation payload (HTTP 400).

Example​

mutation UpdateInvoiceHealthcode($invoiceId: ID!) {
  updateInvoice(
    invoiceId: $invoiceId
    invoiceData: {
      healthcode: {
        status: "Unprocessed"
        providerReference: "EXT-REF-001"
      }
    }
  ) {
    data {
      id
      invoiceNumber
    }
    error
  }
}

Migration​

No breaking schema changes for existing updateInvoice clients. If you submit invoices to Healthcode via your own integration today, you can now record status and providerReference on the Semble invoice instead of tracking outcomes only in your own systems.

See also​