Version	Page Info
Last update	Page Info
Classification	public
Responsible	Product Management

1 Summary
2 Appointment Booking
- 2.1 Overview
- 2.2 Integration Setup
  - 2.2.1 Prerequisites
- 2.3 Resource Interactions
  - 2.3.1 Patient Management
    - 2.3.1.1 Patient Creation
    - 2.3.1.2 Patient Updates Polling
  - 2.3.2 Appointment Scheduling
    - 2.3.2.1 Slot Search
    - 2.3.2.2 Slot Updates Polling
    - 2.3.2.3 Appointment Booking
    - 2.3.2.4 Appointment Cancellation
    - 2.3.2.5 Appointment Rescheduling
    - 2.3.2.6 Appointment Updates Polling
- 2.4 Implementation Notes
  - 2.4.1 Healthcare Service Mapping
3 Questionnaire & QuestionnaireResponse
- 3.1 Questionnaire
  - 3.1.1 Questionnaire Search
  - 3.1.2 Questionnaire Creation
- 3.2 QuestionnaireResponse
  - 3.2.1 Finds or creates the Patient resource based on the form data
    - 3.2.1.1 Patient Search
    - 3.2.1.2 Patient Creation
  - 3.2.2 Creates or finds the corresponding Questionnaire resource
    - 3.2.2.1 Questionnaire Search
    - 3.2.2.2 Questionnaire Creation
  - 3.2.3 Creates or updates the QuestionnaireResponse
    - 3.2.3.1 QuestionnaireResponse Search
  - 3.2.4 QuestionnaireResponse Creation
    - 3.2.4.1 QuestionnaireResponse Updates

Summary

The samedi FHIR-Gateway supports

Terminplanung according to ISiK Stufe 2 from the perspective of a FHIR Requestor and
the unidirectional sending of FHIR Questionnaire and QuestionnaireResponse to a FHIR Repository.

Appointment Booking

Overview

samedi has implemented a FHIR client following the ISiK standard as an Appointment Requestor. This client enables seamless integration between samedi's patient portal, samedi professional, and your FHIR server implementation.

Integration partners need to provide a FHIR server that complies with ISiK specifications.

Integration Setup

Prerequisites

A FHIR server implementing ISiK Terminbuchung Stufe 2
Support for Patient, Schedule, Slot, Appointment, and HealthcareService resources
Support for _history endpoint on resources for change detection (likely to be replaced by FHIR Subscriptions in future versions)
Valid endpoint URL for the FHIR server
Authentication credentials (if required)

Resource Interactions

Patient Management

The client sends patient data to your FHIR server alongside booked or updated appointments.

GET {base-url}/Patient?identifier={system}|{value}

Example:

GET <https://fhir-server.example/fhir/Patient?identifier=https%3A%2F%2Ffhir.krankenhaus.example%2FNamingSystem%2FPID|TestPID>

Patient Creation

Example:

POST <https://fhir-server.example/fhir/Patient>
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "identifier": [{
    "type": {
      "coding": [{
        "system": "<https://terminology.hl7.org/CodeSystem/v2-0203>",
        "code": "MR"
      }]
    },
    "system": "<https://fhir.krankenhaus.example/NamingSystem/PID>",
    "value": "TestPID"
  }],
  "name": [{
    "use": "official",
    "family": "Fürstin von Musterfrau",
    "given": ["Erika"]
  }],
  "address": [{
    "line": [ "Bahnhofstr 12" ],
    "city": "Stadt",
    "postalCode": "12345",
    "country": "DE"
  }],
  "telecom": [{
    "system": "email",
    "value": "email@example.org"
  },{
    "system": "sms",
    "value": "+4901511234567"
  }],
  "gender": "female",
  "birthDate": "1964-08-12"
}

Patient Updates Polling

GET {base-url}/Patient/_history?_since={timestamp}

Example:

GET <https://fhir-server.example/fhir/Patient/_history?_since=2024-08-04T07:19:23.209+00:00>

Appointment Scheduling

Slot Search

GET {base-url}/Slot/?schedule.actor:HealthcareService._id={id}&start=ge{date}&end=le{date}

Example:

GET <https://fhir-server.example/fhir/Slot/?schedule.actor:HealthcareService._id=4&start=ge2024-01-01&end=le2024-01-31>

Slot Updates Polling

GET {base-url}/Slot/_history?_since={timestamp}

Example:

GET <https://fhir-server.example/fhir/Slot/_history?_since=2024-08-04T07:19:23.209+00:00>

Appointment Booking

POST {base-url}/Appointment/$book
Content-Type: application/fhir+json

{
  "parameter": [{
    "name": "appt-resource",
    "resource": {
      "status": "proposed",
      "serviceType": [{
        "coding": [{
          "system": "<https://samedi.de>",
          "code": "ISiKKalenderExample"
        }]
      }],
      "slot": [{
        "reference": "Slot/7"
      }],
      "description": "Akupunkturtermin",
      "start": "2022-01-01T10:00:00Z", 
      "end": "2022-01-01T11:00:00Z",
      "participant": [{
        "actor": {
          "reference": "Patient/5"
        },
        "status": "accepted"
      }],
      "resourceType": "Appointment"
    }
  }],
  "resourceType": "Parameters"
}

Appointment Cancellation

Example:

PATCH <https://fhir-server.example/fhir/Appointment/123>
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "operation",
      "part": [
        {
          "name": "type",
          "valueString": "replace"
        },
        {
          "name": "path",
          "valueString": "status"
        },
        {
          "name": "value",
          "valueString": "cancelled"
        }
      ]
    }
  ]
}

Appointment Rescheduling

For rescheduling, our client:

Cancels the existing appointment (using the cancellation request above)
Creates a new appointment with a reference to the cancelled one:

Example:

POST <https://fhir-server.example/fhir/Appointment/$book>
Content-Type: application/fhir+json

{
  "parameter": [{
    "name": "appt-resource",
    "resource": {
      "resourceType": "Appointment",
      "status": "proposed",
      "serviceType": [{
        "coding": [{
          "system": "<https://samedi.de>",
          "code": "ISiKKalenderExample"
        }]
      }],
      "slot": [{
        "reference": "Slot/8"
      }],
      "description": "Akupunkturtermin",
      "start": "2022-01-01T11:00:00Z", 
      "end": "2022-01-01T12:00:00Z",
      "participant": [{
        "actor": {
          "reference": "Patient/5"
        },
        "status": "accepted"
      }],
      "replaces": [{
        "reference": "Appointment/123"
      }]
    }
  }],
  "resourceType": "Parameters"
}

Appointment Updates Polling

GET {base-url}/Appointment/_history?_since={timestamp}

Example:

GET <https://fhir-server.example/fhir/Appointment/_history?_since=2024-08-04T07:19:23.209+00:00>

Implementation Notes

Healthcare Service Mapping

We map HealthcareService.type codes to our internal appointment types xref
These mappings are used for slot filtering and appointment creation

Questionnaire & QuestionnaireResponse

Questionnaire

Questionnaire Search

GET {base-url}/Questionnaire?identifier={system}|{value}

Example:

GET <https://fhir-server.example/fhir/Questionnaire?identifier=https%3A%2F%2Fsamedi.de%2Ffhir%2Fforms|unique-form-id>

Questionnaire Creation

POST {base-url}/Questionnaire
Content-Type: application/fhir+json

Example:

POST <https://fhir-server.example/fhir/Questionnaire>
Content-Type: application/fhir+json

{
  "resourceType": "Questionnaire",
  "identifier": [{
    "system": "<https://samedi.de/fhir/forms>",
    "value": "unique-form-id"
  }],
  "name": "ANAMNESIS",
  "title": "Anamnesis",
  "status": "active",
  "date": "2024-08-29T08:21:57+02:00",
  "description": "",
  "item": [
    {
      "linkId": "1",
      "text": "Do you have any allergies?",
      "type": "boolean"
    }
  ],
}

QuestionnaireResponse

When handling form submissions, our gateway performs the following steps:

Finds or creates the Patient resource based on the form data
Creates or finds the corresponding Questionnaire resource
Creates or updates the QuestionnaireResponse

Finds or creates the Patient resource based on the form data

Patient Search

GET {base-url}/Patient/{id}

Example:

GET <https://fhir-server.example/fhir/Patient/123>

Patient Creation

Example:

POST <https://fhir-server.example/fhir/Patient>
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "meta": {
    "profile": [
      "<https://gematik.de/fhir/isik/v3/Basismodul/StructureDefinition/ISiKPatient>"
    ]
  },
  "identifier": [{
    "type": {
      "coding": [{
        "system": "<https://terminology.hl7.org/CodeSystem/v2-0203>",
        "code": "MR"
      }]
    },
    "system": "<https://fhir.krankenhaus.example/NamingSystem/PID>",
    "value": "TestPID"
  }],
  "name": [{
    "use": "official",
    "family": "Fürstin von Musterfrau",
    "given": ["Erika"]
  }],
  "active": true,
  "gender": "female",
  "birthDate": "1964-08-12"
}

Creates or finds the corresponding Questionnaire resource

Questionnaire Search

See above

Questionnaire Creation

See above

Creates or updates the QuestionnaireResponse

The gateway implements an intelligent update mechanism for QuestionnaireResponses:

It first searches for an existing QuestionnaireResponse using the identifier
If no existing response is found, it creates a new one
If an existing response is found:
- The gateway compares the content (items/answers) of both responses
- Only updates the response if the content has changed
- Uses PUT request with the existing resource ID for updates

QuestionnaireResponse Search

GET {base-url}/QuestionnaireResponse?identifier={system}|{value}

Example:

GET <https://fhir-server.example/fhir/QuestionnaireResponse?identifier=https%3A%2F%2Fsamedi.de%2Ffhir%2Fforms|unique-form-id>

QuestionnaireResponse Creation

Example:

POST <https://fhir-server.example/fhir/QuestionnaireResponse>
Content-Type: application/fhir+json

{
  "resourceType": "QuestionnaireResponse",
  "identifier": {
    "system": "<https://samedi.de/fhir/forms>",
    "value": "unique-form-id"
  },
  "questionnaire": "Questionnaire/123",
  "status": "completed",
  "subject": {
    "reference": "Patient/456"
  },
  "authored": "2024-03-14T15:30:00Z",
  "item": [
    {
      "linkId": "1",
      "text": "Do you have any allergies?",
      "answer": [
        {
          "valueBoolean": false
        }
      ]
    }
  ]
}

QuestionnaireResponse Updates

Example:

PUT <https://fhir-server.example/fhir/QuestionnaireResponse/123>
Content-Type: application/fhir+json

{
  "resourceType": "QuestionnaireResponse",
  "identifier": {
    "system": "<https://samedi.de/fhir/forms>",
    "value": "unique-form-id"
  },
  "questionnaire": "Questionnaire/123",
  "status": "completed",
  "subject": {
    "reference": "Patient/456"
  },
  "authored": "2024-03-14T15:30:00Z",
  "item": [
    {
      "linkId": "1",
      "text": "Do you have any allergies?",
      "answer": [
        {
          "valueBoolean": false
        }
      ]
    },
    {
      "linkId": "2",
      "text": "When was your last medical checkup?",
      "type": "date"
    },
  ]
}