REST API for HIS Integration

For each case to code, the HIS opens a coding session, embeds the returned URL in an iframe, and either receives the result via webhook or pulls it from a GET endpoint.

Open a coding session

The HIS POSTs the patient SPIGES XML wrapped as data. instanceId is HIS-supplied — it correlates the submission (one POST), not each case inside it. The data payload can carry one or many SPIGES <Fall> elements; they all belong to the same coding session and share the same instanceId. The id MUST be unique — a second POST with an instanceId still in use returns 409 Conflict with the existing sessionId in the body; the id becomes free once the original session completes. KodeMed echoes it back in the webhook so the HIS matches the result against its original submission. sessionId is server-generated.

The 201 response carries sessionId (UUID v4) and redirectUrl. The HIS embeds the redirectUrl in an iframe.

Pull the result (fallback when not using a webhook)

Two identifiers, one source of truth

• instanceId — HIS-supplied correlator for the submitted data payload. One instanceId maps to one POST; the payload may carry one or many SPIGES <Fall> cases — all share this id. MUST be unique across active sessions (duplicate → 409 Conflict). Echoed back in the webhook for HIS-side matching.
• sessionId — UUID v4 generated by KodeMed when accepting the session. Used by the iframe URL, the result GET, and the webhook payload. Use it for KodeMed-side tracing.

There is no separate correlationId in the contract — only the two above. The OpenAPI spec (linked below) is the source of truth.

Webhook Contract Server-side dispatch — #493 in flight

For HIS REST integrations, KodeMed fires the webhook server-side when the coder clicks Apply or Discard. The URL, signing strategy, retry schedule and event filter are configured per-IntegrationProfile via the admin API (#492); there are no env vars for this flow.

For the legacy DLL flow, the HTTP POST is fired by the DLL itself and configured via the KODEMED_HOOK_* env vars on the Server. See the Configuration Reference → DLL Webhook for that path.

Outbound payload

Retry schedule

• 4 attempts: ~30s, ~2min, ~10min between attempts (configurable per profile).
• HTTP 5xx, 429, network errors → retried.
• HTTP 4xx (except 429) → terminal → payload moves to the dead-letter queue (DLQ).
• DLQ replay through the admin API (#494): POST /api/v1/admin/webhook-failures/{id}/replay.

Signature verification (HMAC-SHA256)

When webhook.signing=HMAC_SHA256 is set on the IntegrationProfile, the HIS reads the Authorization: HMAC-SHA256 t=<unix>,v1=<hex> header and re-computes HMAC-SHA256 over <t>.<raw body> with the shared secret. Reject the request if the timestamp is older than 5 minutes (replay protection).

Node receiver:

Python receiver:

External OIDC IDP Setup Multi-issuer — #495 in flight

The HIS keeps its own OIDC-compliant Identity Provider — Keycloak, Azure AD, Okta, Auth0, Ping, Authelia, KodeMed’s bundled Keycloak, any vendor that implements OpenID Connect Discovery + RS256-signed JWTs. KodeMed validates the JWT against the configured issuer; no second login on the KodeMed side, no federation, no token exchange.

Issuer configuration

• Issuer URL format: whatever your IDP publishes. Common shapes — Keycloak: https://<host>/realms/<realm>; Azure AD: https://login.microsoftonline.com/<tenant>/v2.0; Okta: https://<org>.okta.com/oauth2/default. The exact value is what appears in the iss claim of issued tokens.
• JWKS auto-discovery via <issuer>/.well-known/openid-configuration — no manual key exchange. KodeMed reads jwks_uri from the discovery document and refreshes keys on rotation.
• Algorithm: RS256 (asymmetric). HS256 / symmetric secrets are not accepted — they require sharing the signing key with KodeMed, which defeats the IDP boundary.
• Audience (aud) check: optional; configurable per IntegrationProfile (oidc.audience).
• Multi-issuer: KodeMed can validate tokens from N issuers (test + prod, or several HIS partners). Each issuer corresponds to one IntegrationProfile — different partners can run different IDP products side by side.
• The KodeMed host needs HTTPS reachability to the issuer URL.

Required token claims

Required role names

Configure the following role (or group) names in your IDP so authorisation works by default. On Keycloak that’s a realm role; on Azure AD an app-role mapped through groups; on Okta a group claim. Override the names per profile if the partner cannot use these defaults.

• kodemed-coder — access to the coding UI and POST /api/v1/coding/session.
• kodemed-admin — access to admin endpoints (/api/v1/admin/*) including DLQ replay.
• kodemed-viewer — read-only access (optional; not enforced today, planned).

Iframe Embed + CSP Per-profile CSP — #496 in flight

The HIS opens KodeMed’s redirectUrl in an <iframe>. KodeMed sets Content-Security-Policy: frame-ancestors to allow only the configured HIS hostnames; everything else is blocked.

• Configure per IntegrationProfile: embed.csp_frame_ancestors: ["https://your-his-test.example.com", "https://your-his.example.com"] (admin API).
• Cookies on the KodeMed UI are already SameSite=None; Secure, so cross-origin iframe sessions work without changes on the HIS side.
• Legacy: the demo deployment historically used X-Frame-Options: DENY. The new flow replaces this with the per-profile CSP frame-ancestors.

OpenAPI Specifications

The full contract is published as OpenAPI 3.1 by every service. Same paths apply on a self-hosted installation — substitute your KodeMed hostname.

The Authorize button on Swagger UI accepts a test JWT directly, once your realm issuer is configured.

Interconnection Matrix

Which component talks to which. Use this to size a deployment, open firewall holes, or scope a security review. Read each section for a different concern — A is what to expose externally, B is egress your network must allow, C is intra-host wiring (Docker compose / OpenShift), D is local-machine COM bridges.

A. Customer-facing — partner / browser ↔ KodeMed via Caddy on port 443

Open these in the partner firewall. Public URL hosts are the canonical ones (kodemed.ch subdomains); your on-prem install will substitute its own.

B. Outbound from KodeMed — egress rules

Allow these in the KodeMed host's outbound firewall. Endpoints reach the public internet (or partner-side webhooks).

C. Internal — container ↔ container on the host network

These ports are NOT exposed externally. Docker compose wires them on the kodemed network; OpenShift wires them via Services. Open them in firewall ONLY if you split components across hosts.

D. Local-machine — COM DLL bridge (Windows host only)

In-process COM activation + a loopback WebSocket between the COM DLL and the CodingClient tray. Nothing leaves the workstation.

Auth column conventions — OIDC JWT (user) is the browser-bearer access token (audience: kodemed-ui). service JWT (internal) is the audience-restricted token issued by KodeMed Server to call DataServer / Grouper. HMAC-SHA256 applies only to HIS webhooks. All HTTPS hops carry standard security headers (HSTS, CSP, X-Frame-Options) enforced by SecurityConfig. See Roles & Permissions for the role-name table.

Sequence — HIS REST integration

Happy-path flow from HIS-initiated session create to webhook delivery + result fetch.

sequenceDiagram
    autonumber
    participant HIS as HIS
    participant IDP as Partner OIDC IDP
    participant S as KodeMed Server
    participant UI as KodeMed UI
    participant WH as HIS webhook

    HIS->>IDP: client_credentials
    IDP-->>HIS: JWT
    HIS->>S: POST /api/v1/coding/session
{ data, format:"spiges", source:"API", instanceId }
    S->>S: validate JWT (JWK)
    S->>S: persist session
    S-->>HIS: 201 { sessionId, redirectUrl, expiresAt }
    HIS->>UI: load redirectUrl in iframe
    Note over UI: coder edits, presses Apply
    UI-->>S: result
    S->>WH: HMAC-sign + POST
{ event_type, occurred_at, session_id,
instance_id, spiges, result_data }
    WH-->>S: 2xx
    opt HIS without webhook
        HIS->>S: GET /api/v1/coding/session/{id}/result/data
        S-->>HIS: 200 result_data
    end

If the webhook gets a 5xx/timeout, KodeMed retries with the per-tenant webhookRetryDelaysSeconds (default 30s, 2m, 10m) and persists to the dead-letter queue if all attempts fail (replay via POST /api/v1/admin/webhook-failures/{id}/replay).

Sequence — DLL / CodingClient flow Legacy

In-process integration via the COM DLL for HIS that cannot make HTTPS calls but can load a Windows DLL. Same end-state (modified SPIGES returned to HIS) but the transport is COM ↔ loopback WebSocket ↔ KodeMed Server.

sequenceDiagram
    autonumber
    participant HIS as HIS process
    participant DLL as COM DLL
    participant CC as CodingClient (tray)
    participant S as KodeMed Server
    participant B as Browser

    HIS->>DLL: StartCoding(spiges)
    DLL->>CC: ws://127.0.0.1:9876
    CC->>S: wss /ws/dll (JWT)
    S-->>CC: ack
    CC->>S: CODING_SESSION_LAUNCH { sessionId, data }
    S->>B: open in browser
    Note over B: coder edits, presses Apply
    S-->>CC: CODING_SESSION_COMPLETE (sessionId, result)
    CC-->>DLL: result
    DLL-->>HIS: result (SPIGES)

The DLL writes the modified SPIGES back to the HIS in-process. No outbound webhook is fired in this flow — the HIS already has the result by the time StartCoding returns.

Sequence — Webhook retry + dead-letter

Failure path. Server retries on 5xx / 408 / 429 / network errors with the per-tenant webhookRetryDelaysSeconds schedule; after the last attempt the payload is persisted to the WebhookFailure dead-letter table and an admin can replay it.

sequenceDiagram
    autonumber
    participant S as KodeMed Server
    participant WH as HIS webhook
    participant DLQ as WebhookFailure (DLQ)
    participant ADM as Admin

    S->>WH: attempt 1 (POST)
    WH-->>S: 503
    Note over S: wait 30s
    S->>WH: attempt 2 (POST)
    WH-->>S: timeout
    Note over S: wait 2m
    S->>WH: attempt 3 (POST)
    WH-->>S: 502
    Note over S: wait 10m
    S->>WH: attempt 4 (POST)
    WH-->>S: 502
    S->>DLQ: persist row
{ profileSlug, sessionId, instanceId,
eventType, payload, attempts:4,
lastError, lastHttpStatus }
    ADM->>DLQ: GET /api/v1/admin/webhook-failures
    DLQ-->>ADM: 200 [ {id,…}, … ]
    ADM->>S: POST .../{id}/replay
    S->>WH: replay POST
    WH-->>S: 200
    S->>DLQ: mark row delivered

Retry schedule + max attempts are stored on the IntegrationProfile per partner. Default is 4 attempts at 30s / 2m / 10m / 1h. Idempotency: the Idempotency-Key header is stable across retries so the HIS can dedupe.

Sequence — REST polling fallback

For HIS that cannot host a public webhook endpoint. Create the session, poll for completion. Same end-state as the webhook flow but driven by the HIS.

sequenceDiagram
    autonumber
    participant HIS as HIS
    participant S as KodeMed Server
    participant UI as KodeMed UI

    HIS->>S: POST /api/v1/coding/session
    S-->>HIS: 201 { sessionId, redirectUrl, expiresAt }
    HIS->>UI: open redirectUrl in iframe
    Note over UI: coder edits, presses Apply
    UI-->>S: result
    loop poll every 5-30s
        HIS->>S: GET /api/v1/coding/session/{id}/status
        S-->>HIS: 200 { status:"COMPLETED", action:"APPLIED" }
    end
    HIS->>S: GET /api/v1/coding/session/{id}/result/data
    S-->>HIS: 200 result_data (SPIGES)

Recommended poll interval: 5s while the iframe is visible, 30s after it closes. The expiresAt on the create response upper-bounds how long the session is pollable.

Sequence — CodingClient WebSocket /ws/dll

For native desktop integrations that already speak WebSocket. Skip the DLL transport; speak /ws/dll directly to the Server. Same message vocabulary as the DLL flow.

sequenceDiagram
    autonumber
    participant NC as Native client
    participant S as KodeMed Server
    participant B as Browser (UI)

    NC->>S: wss /ws/dll ?token=JWT
    S-->>NC: HELLO { instanceId }
    NC->>S: REGISTER { user, instance }
    S-->>NC: REGISTERED
    NC->>S: CODING_SESSION_LAUNCH
{ instanceId, data:SPIGES }
    S-->>NC: SESSION_OPENED { sessionId }
    S->>B: open in browser
    Note over B: coder Apply
    B-->>S: result
    S-->>NC: CODING_SESSION_COMPLETE
{ sessionId, result_data }

The token is validated on every frame; an expired JWT closes the socket with code 4001. Reconnect with a refreshed token to resume; the server holds the session-id mapping in-memory for sessionExpiryMinutes.

Sequence — DataServer thesaurus lookup

For HIS that wants to autocomplete ICD-10 / CHOP / ATC codes in its own UI before opening a coding session. Direct REST call against the DataServer.

sequenceDiagram
    autonumber
    participant UI as HIS UI
    participant DS as DataServer
    participant PG as PostgreSQL

    UI->>DS: GET /api/thesaurus/search?q=J96.0
Authorization: Bearer JWT
    DS->>PG: SELECT … LIMIT 20
    PG-->>DS: rows
    DS-->>UI: 200 [ { code, label, version, … } ]
    UI->>DS: GET /api/thesaurus/rules/code/ICD10/J96.0?version=2026
    DS->>PG: SELECT rules WHERE code=$1 AND version=$2
    PG-->>DS: rows
    DS-->>UI: 200 { rules:[ { kind:"INCLUSION", text:"…" }, … ] }

Cached at If-None-Match / ETag; year-versioned so a 2026 lookup can never silently fall back to 2025 data. Full schema in the DataServer Swagger UI.

Sequence — Grouper grouping

For HIS that wants to run a real-time SwissDRG / TARPSY / ST Reha grouping without involving a coder. Direct REST call against the Grouper.

sequenceDiagram
    autonumber
    participant HIS as HIS
    participant G as Grouper
    participant DS as DataServer

    HIS->>G: POST /api/v1/grouper/group
{ tariff:"SWISSDRG", version:"15.0",
case:{ Fall:…, Diag:[…], Proc:[…] } }
    G->>G: load specs + catalogue (cached)
    G->>DS: POST /api/zusatzentgelt/match
    DS-->>G: supplements []
    G-->>HIS: 200 { drg:"E62A", kostengewicht:1.234,
supplements:[…], trace:[…] }

The trace field carries the grouping decision path so a HIS audit log can reconstruct why a given DRG was assigned. GET /api/v1/grouper/versions lists the tariff × year combinations the deployment supports.

Sequence — OIDC login + iframe session cookie

How the clinician's JWT becomes a same-site cookie that survives the iframe load when the UI is embedded inside the HIS page.

sequenceDiagram
    autonumber
    participant B as Browser (HIS page)
    participant IDP as Partner OIDC IDP
    participant UI as KodeMed UI
    participant S as KodeMed Server

    B->>UI: iframe src=redirectUrl
    UI->>S: /actuator/info
    S-->>UI: 200
    UI->>UI: load runtime-config (issuer URL, etc.)
    B->>IDP: (silent) /authorize?prompt=none
    IDP-->>B: 302 with code
    B->>IDP: /token (PKCE)
    IDP-->>B: id_token + access_token + refresh
    B->>UI: set SameSite=None Secure cookie
    UI->>S: REST + WS calls
Authorization: JWT

The HIS site must be listed in IntegrationProfile.embedCspFrameAncestors for the browser to accept the iframe. The SameSite=None cookie attribute is mandatory for cross-origin iframe sessions and is the default for HIS REST integrations.

SPIGES XSD Schema

Validate caseData / resultData against the SPIGES XML schema before posting to /api/v1/coding/session or before accepting a webhook payload. Pin to a specific version — KodeMed will publish each new revision side-by-side.

• SPIGES 1.5 · do-d-14.04-SPIGES-2025-02.xsd — current

XSD validation samples in C# / Java / Python are bundled in the Test.UI partner sample below.

Reference Sample — KodeMed.Test.UI C# / WinForms Apache 2.0

A single-window C# WinForms app that exercises every integration entry point in one place: REST session create, iframe embed, WebSocket signalling, webhook receiver stub, DLL/COM call. Use it as a partner reference implementation — the screen labels match the REST and WebSocket field names so you can map your own HIS code 1:1.

• kodemed/KodeMed.Test.UI on GitBucket — canonical source, fork it / open PRs / track upstream
• KodeMed.Test.UI · offline sources (.csproj + .cs + .ico) — .NET 9, no bin/obj, ready to dotnet run

Clone or download:

# Option 1 — clone the GitBucket repo (always up to date)
git clone ssh://git@www.mieresit.com:7777/kodemed/KodeMed.Test.UI.git
cd KodeMed.Test.UI
dotnet run

# Option 2 — offline zip
unzip KodeMed.Test.UI-sources.zip
cd KodeMed.Test.UI
dotnet run

License CLI Tool

Download the CLI JAR to generate and verify license files.

• kodemed-license-cli.jar Download JAR
• Quick Reference java -jar kodemed-license-cli.jar generate --private-key key.pem --type DEMO --org "Hospital" --days 90 --output kodemed.license

Server — Feedback / GitBucket integration

The Server forwards user feedback to GitBucket (issues) and SMTP (email). All keys can be left empty in environments where neither is desired. Disable the entire subsystem with KODEMED_FEEDBACK_ENABLED=false.

Server Webhook (HIS REST integration) Per-IntegrationProfile · #493 in flight

For HIS REST integrations the Server fires the webhook itself. Configuration is per-IntegrationProfile in the database (set via the admin API, #492). There are no env vars for this flow — the values below are profile fields, not .env entries.

For the full payload shape, retry semantics, DLQ replay path and HMAC signature verification snippets, see Integration → Webhook Contract.

KodeMed DataServer Port 8081

Data import/export service — ICD-10, CHOP, thesaurus, hot-folder import.

KodeMed GrouperServer Port 8082

DRG grouper — stateless service for SwissDRG, TARPSY, ST Reha grouping. No database required.

KodeMed CodingUI Port 3000

React frontend served via nginx. Configured at runtime via runtime-config.js.

Caddy / reverse proxy Compose overlay

These variables shape Caddyfile.* and the per-service routing in docker-compose.caddy.yml. They have no effect on KodeMed services themselves — only on the TLS / hostname layer.

Portal — OAuth2-Proxy Demo + prod

The portal pages (downloads demo + prod) are protected by oauth2-proxy sidecars in docker-compose.demo.yml. Two distinct OIDC clients allow demo-portal and prod-portal to live behind the same Keycloak realm without sharing cookies.

Keycloak (bundled mode) SSO

Used by the wizard’s localhost preset and by the optional docker-compose.keycloak.yml overlay. Customers using their own Keycloak (HIS REST integrations) do not need any of these — only the issuer URL matters then.

KodeMed DLL/Client C# Desktop

Windows desktop DLL integration. Config file: kodemed-client-config.json (next to DLL or %APPDATA%\KodeMed\).

Health Check & Smoke Test Endpoints

Use these public endpoints (no authentication required) to verify your deployment:

HTTP 402 on any endpoint means the license is invalid or missing. Check KODEMED_LICENSE_FILE path and verify with: java -jar kodemed-license-cli.jar verify --public-key kodemed-public.pem --license kodemed.license