Änderungen abrufen (Provenance Search)

Beschreibung und fachlicher Kontext

Um zu gewährleisten, dass sich das Software-System kontinuierlich mit dem 116117 Terminservice synchronisieren (d.h., regelmäßig alle Änderungen an abrechnungsrelevanten Informationen abrufen) kann, wird ein Endpunkt zur Verfügung gestellt, der nur die letzten Änderungen an den im System des 116117 Terminservice gespeicherten Terminbuchungen zurückgibt.

Hierfür dient die spezielle Ressource Provenance, die eine entsprechende Struktur abbildet, um die letzte Änderung an einer Terminbuchung zu dokumentieren und die auf der Seite Profil: Änderung (Provenance) im Detail beschrieben ist.

Beim Abrufen der Provenances handelt es sich um die FHIR-Standardinteraktion search.

Der Abruf ist für die kontinuierliche Synchronisation mit dem 116117 Terminservice notwendig. Dafür müssen alle für die im Software-System hinterlegte Praxis relevanten Änderungen, die seit dem letzten Abruf vorgenommen wurden, vom 116117 Terminservice abgerufen werden.


Request

Das Abrufen der Änderungen erfordert einen POST-Request, mit dem entweder alle Änderungen an Terminbuchungen von allen autorisierten Einrichtungen oder nur Änderungen an Terminbuchungen von bestimmten autorisierten Einrichtungen (mittels Suchparameter im Request Body) abgefragt werden können.


HTTP Method POST
URL https://abrechnungsinformation.eterminservice.kv-safenet.de/pvs​/abrechnungsinformation/api/Provenance/_search
Request Body [suchparameter]

Bitte beachten: Laut FHIR-Standard wäre auch eine Suche mit Suchparametern innerhalb der URL und/oder mittels GET-Request möglich, was durch die Systeme des 116117 Terminservices jedoch NICHT unterstützt wird. Ein GET-Request auf die unten angegebene URL führt zu einem Fehler. Suchparameter in der URL werden von den Systemen des 116117 Terminservices ignoriert, d.h. weder validiert noch verarbeitet.


Folgende Request Header werden von den Systemen des 116117 Terminservices unterstützt und verarbeitet:

Header Verpflichtend? Beschreibung Wert
Authorization ja Im Authentisierungsverfahren erhaltene ACCESS_TOKEN als Bearer Token Bearer ey...
Content-Type ja Gibt den ursprünglichen Medien- bzw. Dateitypen der Ressource an. application/x-www-form-urlencoded
Accept nein Gibt an, welche Inhaltstypen die Systeme des Anfragenden verstehen.
Der 116117 Terminservice unterstützt nur fhir+xml.		 application/fhir+xml

Request Body

Der Request Body muss alle Suchparameter enthalten, nach denen die Suchergebnisse gefiltert werden sollen.

In den folgenden Abschnitten werden die einzelnen Suchparameter im Detail beschrieben. Suchparameter, die hier nicht aufgelistet sind, aber dennoch im Request Body übergeben werden, werden von den Systemen des 116117 Terminservices ignoriert, d.h. weder validiert noch verarbeitet.


Bitte beachten: Die Systeme des 116117 Terminservices prüfen bei Angabe mehrerer Suchparameter nur bedingt auf Plausibilität, was bedeutet, dass nicht zwangsweise eine Fehlermeldung als Response zurückkommt, wenn sich mehrere Suchparameter gegenseitig ausschließen (bspw. UND-Verknüpfung bei mehreren BSNRs oder UND-Verknüpfung einer ANR und einer BSNR, wobei der zur ANR zugehörige Arzt nicht in der Praxis / medizinischen Einrichtung arbeitet, die zur angegebene BSNR gehört). In solch einem Fall kommt stattdessen der HTTP-Statuscode 200 OK mit einem leeren Suchergebnis zurück.


Suchparameter: Betriebsstättennummer (BSNR)

Parameter bsnr
Beschreibung 9-stellige BSNR der Praxis / medizinischen Einrichtung
Kardinalität 0..*
Erlaubte Verknüpfungen1 ODER-Verknüpfung
Erlaubte Präfixe2 -
Suchergebnis Alle Provenances, die Änderungen an Terminbuchungen betreffen, die von den Praxen / medizinischen Einrichtungen angeboten werden, zu denen die angegebenen BSNRs gehören.
Anmerkung

Bei der BSNR handelt es sich um einen custom search parameter, der auf der Seite Suchparameter: BSNR (SearchParameter) näher beschrieben ist.

Wird keine BSNR übergeben, so werden die BSNRs aus dem JWT als Suchparameter übernommen.

Suchparameter: Änderungszeitpunkt

Parameter recorded
Beschreibung Zeitpunkt des letzten Abrufs
Kardinalität 0..1
Erlaubte Verknüpfungen1 -
Erlaubte Präfixe2 gt (greater than / größer als)
Suchergebnis Alle Provenances, deren Zeitpunkt der vorgenommenen Änderung nach dem definierten Zeitpunkt liegt.
Anmerkung Wie nach Zeitpunkten gefiltert werden kann, ist in der HL7-FHIR-Dokumentation unter Search – Standard Parameters: date beschrieben.

Suchparameter: Anzahl der Suchergebnisse

Parameter _count
Beschreibung Anzahl der Suchergebnisse pro Seite
Kardinalität 0..1
Erlaubte Verknüpfungen1 -
Erlaubte Präfixe2 -
Suchergebnis Es werden maximal so viele Änderungen an Terminbuchungen zurückgegeben, wie in _count angegeben wurde.
Anmerkung Wird keine Anzahl angegeben, so wird der Standardwert von 10 als Suchparameter übernommen.

1 Wie Parameter mit UND bzw. ODER verknüpft werden können, ist in der HL7-FHIR-Dokumentation unter Search – Standard Parameters: Composite Search Parameters beschrieben.

2 Die Präfixe sind in der HL7-FHIR-Dokumentation unter Search – Standard Parameters: Prefixes beschrieben.


Beispiele

Beispiel 1: Suche anhand einer BSNR

# Suche alle Provenances, die Änderungen an Terminbuchungen enthalten, die von der Praxis mit der BSNR 123456789 angeboten werden
POST https://abrechnungsinformation.eterminservice.kv-safenet.de/pvs​/abrechnungsinformation/api/Provenance/_search
Content-Type: application/x-www-form-urlencoded
bsnr=123456789

Beispiel 2: Suche anhand eines Änderungszeitpunktes

# Suche alle Provenances, die Änderungen an Terminbuchungen enthalten, deren Änderungszeitpunkt zeitlich nach dem 14.01.2024, 12:11:17 Uhr liegt
POST https://abrechnungsinformation.eterminservice.kv-safenet.de/pvs​/abrechnungsinformation/api/Provenance/_search
Content-Type: application/x-www-form-urlencoded
recorded=gt2024-01-14T12:11:17-01:00

Beispiel 3: Suche anhand einer BSNR und eines Änderungszeitpunktes

# Suche alle Provenances, die Änderungen an Terminbuchungen enthalten, die von der Praxis mit der BSNR 123456789 angeboten werden und wo der Änderungszeitpunkt zeitlich nach dem 14.01.2024, 12:11:17 Uhr liegt
POST https://abrechnungsinformation.eterminservice.kv-safenet.de/pvs​/abrechnungsinformation/api/Provenance/_search
Content-Type: application/x-www-form-urlencoded
recorded=gt2024-01-14T12:11:17-01:00&bsnr=123456789

Response

Für die Suche von Provenances wird im Erfolgsfall der HTTP-Statuscode 200 OK sowie ein Searchset Bundle im Response Body zurückgegeben.

  • Wurden bei der Suche keine Suchparameter übergeben, enthält das zurückgegebene Searchset alle noch vorhandenen Provenanes mit Änderungen an Terminbuchungen der Haupt- und Nebenbetriebsstätten der in der Autorisierung übergebenen BSNR.

  • Wurde bei der Suche min. ein Suchparameter übergeben, enthält dieses Searchset alle Provenances, die anhand der Suchparameter in Verbindung mit den autorisierten BSNRs ermittelt werden konnten.

Im Fehlerfall wird ein dem Fehler entsprechender HTTP-Statuscode (bspw. 400 Bad Request oder 500 Internal Server Error) sowie ein OperationOutcome im Response Body zurückgegeben. Dieses OperationOutcome enthält Details zum aufgetretenen Fehler.


Header

Folgende Response Header werden von den Systemen des 116117 Terminservices gesetzt und an den Anfragenden zurückgesendet:

Header Beschreibung Wert
Content-Type Gibt den ursprünglichen Medien- bzw. Dateitypen der Ressource an. application/fhir+xml

Response Body

Im Erfolgsfall ist im Response Body ein Searchset Bundle enthalten, welches ein Set an Suchergebnissen enthält. Dieses Set kann auch leer sein, wenn anhand der gesetzten Suchparameter keine passenden Provenances gefunden werden konnten. Details hierzu sind unter Profil: Suchergebnisse (Bundle) zu finden.

Im Fehlerfall ist im Response ein OperationOutcome enthalten. Details hierzu sind unter Profil: Fehler (OperationOutcome) zu finden.


Beispiele

Alle Beispiele für den Erfolgsfall sind hier im vorliegenden Projekt zu finden.

Alle Beispiele für den Fehlerfall sind hier im vorliegenden Projekt zu finden.


<Bundle xmlns="http://hl7.org/fhir">
    <meta>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Bundle_Searchset|0.2.0" />
    </meta>
    <type value="searchset" />
    <timestamp value="2024-09-02T12:34:56+02:00" />
    <total value="2" />
    <link>
        <relation value="self" />
        <url value="https://fhir.kbv.de/Provenance?bsnr=123456789&amp;recorded=gt2024-09-01T00:00:00+01:00&amp;_count=25" />
    </link>
    <entry>
        <fullUrl value="urn:uuid:dd4c41b2-7b25-4019-a3b6-d63514439519" />
        <resource>
            <Provenance>
                <id value="dd4c41b2-7b25-4019-a3b6-d63514439519" />
                <meta>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Provenance|0.2.0" />
                </meta>
                <text>
                    <status value="extensions" />
                    <div xmlns="http://www.w3.org/1999/xhtml"><h1>Provenance dd4c41b2-7b25-4019-a3b6-d63514439519</h1><p>Änderung: Update</p><p>Geänderte Ressource: Slot/4a758a29-bd28-4970-a08a-91bf91b82cd3</p><p>Geändert durch: Terminservicestelle (TSS) der 116117 Hotline</p><p>Zeitpunkt: 2024-09-03T04:43:25</p></div>
                </text>
                <target>
                    <reference value="urn:uuid:ac613a2c-91c5-4eb4-9ab4-e99629a1fa15" />
                    <type value="Appointment" />
                </target>
                <recorded value="2024-09-03T04:43:25+02:00" />
                <activity>
                    <coding>
                        <system value="http://terminology.hl7.org/CodeSystem/v3-DataOperation" />
                        <code value="UPDATE" />
                        <display value="revise" />
                    </coding>
                </activity>
                <agent>
                    <who>
                        <display value="Terminservicestelle (TSS) der 116117 Hotline" />
                    </who>
                </agent>
            </Provenance>
        </resource>
        <search>
            <mode value="match" />
        </search>
    </entry>
    <entry>
        <fullUrl value="urn:uuid:0f5606a5-6a59-4ff3-b4f2-f3a6a1b6d20c" />
        <resource>
            <Provenance>
                <id value="0f5606a5-6a59-4ff3-b4f2-f3a6a1b6d20c" />
                <meta>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Provenance|0.2.0" />
                </meta>
                <text>
                    <status value="extensions" />
                    <div xmlns="http://www.w3.org/1999/xhtml"><h1>Provenance 0f5606a5-6a59-4ff3-b4f2-f3a6a1b6d20c</h1><p>Änderung: Create</p><p>Geänderte Ressource: Appointment/3545c894-1a5c-4ef6-9b68-9e4595c2bf71</p><p>Geändert durch: 116117 Terminservice</p><p>Zeitpunkt: 2024-09-03T04:43:25</p></div>
                </text>
                <target>
                    <reference value="urn:uuid:eac5e3b4-9d20-4fa1-a900-cb27f4ea8fb6" />
                    <type value="Appointment" />
                </target>
                <recorded value="2024-09-03T04:43:25+02:00" />
                <activity>
                    <coding>
                        <system value="http://terminology.hl7.org/CodeSystem/v3-DataOperation" />
                        <code value="CREATE" />
                        <display value="create" />
                    </coding>
                </activity>
                <agent>
                    <who>
                        <display value="116117 Terminservice" />
                    </who>
                </agent>
            </Provenance>
        </resource>
        <search>
            <mode value="match" />
        </search>
    </entry>
    <entry>
        <fullUrl value="urn:uuid:ac613a2c-91c5-4eb4-9ab4-e99629a1fa15" />
        <resource>
            <Appointment>
                <id value="ac613a2c-91c5-4eb4-9ab4-e99629a1fa15" />
                <meta>
                    <versionId value="1" />
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Appointment|0.5.0" />
                </meta>
                <text>
                    <status value="extensions" />
                    <div xmlns="http://www.w3.org/1999/xhtml">Diese Appointment-Instanz enthält einen Termin am 2024-01-14 von 12:15 bis 12:45 Uhr für das Leistungsmerkmal 20 (Arztgruppe)</div>
                </text>
                <extension url="https://fhir.kbv.de/StructureDefinition/KBV_EX_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Appointment_Booked_By">
                    <valueCodeableConcept>
                        <coding>
                            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Roles" />
                            <version value="0.3.0" />
                            <code value="​Patient" />
                            <display value="Patient" />
                        </coding>
                    </valueCodeableConcept>
                </extension>
                <status value="booked" />
                <serviceType>
                    <coding>
                        <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAS_FACHGEBIET_GROB" />
                        <code value="20" />
                        <display value="Humangenetik" />
                    </coding>
                </serviceType>
                <priority>
                    <extension url="https://fhir.kbv.de/StructureDefinition/KBV_EX_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Urgency">
                        <valueCoding>
                            <system value="http://snomed.info/sct" />
                            <code value="709122007" />
                            <display value="As soon as possible" />
                        </valueCoding>
                    </extension>
                </priority>
                <start value="2024-01-14T12:15:00+01:00" />
                <end value="2024-01-14T12:45:00+01:00" />
                <created value="2024-01-29T09:23:05+02:00" />
                <basedOn>
                    <identifier>
                        <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_116117_TERMINSERVICE_Vermittlungscode" />
                        <value value="XN6PF4HPZ5KX" />
                    </identifier>
                </basedOn>
                <participant>
                    <actor>
                        <reference value="urn:uuid:55ddacce-3257-44d4-a9dd-a04fb7247723" />
                    </actor>
                    <status value="accepted" />
                </participant>
                <participant>
                    <actor>
                        <reference value="urn:uuid:529c2a3a-7f3c-4d17-9f15-595b29b4cf9c" />
                    </actor>
                    <status value="accepted" />
                </participant>
            </Appointment>
        </resource>
        <search>
            <mode value="include" />
        </search>
    </entry>
    <entry>
        <fullUrl value="urn:uuid:eac5e3b4-9d20-4fa1-a900-cb27f4ea8fb6" />
        <resource>
            <Appointment>
                <id value="eac5e3b4-9d20-4fa1-a900-cb27f4ea8fb6" />
                <meta>
                    <versionId value="2" />
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Appointment|0.5.0" />
                </meta>
                <text>
                    <status value="extensions" />
                    <div xmlns="http://www.w3.org/1999/xhtml">Diese Appointment-Instanz enthält einen Termin am 2024-01-27 von 10:15 bis 10:30 Uhr für die Leistungsmerkmale 09 (Arztgruppe) und 341 (WBO)</div>
                </text>
                <extension url="https://fhir.kbv.de/StructureDefinition/KBV_EX_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Appointment_Booked_By">
                    <valueCodeableConcept>
                        <coding>
                            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_Base_Role_Care_Team" />
                            <version value="1.7.0" />
                            <code value="HA" />
                            <display value="Hausarzt/-&#228;rztin" />
                        </coding>
                    </valueCodeableConcept>
                </extension>
                <status value="cancelled" />
                <cancelationReason>
                    <coding>
                        <system value="http://terminology.hl7.org/CodeSystem/appointment-cancellation-reason" />
                        <code value="pat" />
                        <display value="Patient" />
                    </coding>
                </cancelationReason>
                <serviceType>
                    <coding>
                        <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAS_FACHGEBIET_GROB" />
                        <code value="09" />
                        <display value="Kinder- und Jugendmedizin" />
                    </coding>
                </serviceType>
                <serviceType>
                    <coding>
                        <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR2_WBO" />
                        <code value="341" />
                        <display value="F&#196;/FA Kinder- und Jugendmedizin" />
                    </coding>
                </serviceType>
                <priority>
                    <extension url="https://fhir.kbv.de/StructureDefinition/KBV_EX_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Urgency">
                        <valueCoding>
                            <system value="http://snomed.info/sct" />
                            <code value="103391001" />
                            <display value="Urgent" />
                        </valueCoding>
                    </extension>
                </priority>
                <start value="2024-01-27T10:15:00+01:00" />
                <end value="2024-01-27T10:30:00+01:00" />
                <created value="2024-01-05T11:34:15+02:00" />
                <comment value="Patient allergisch gegen Latex" />
                <basedOn>
                    <identifier>
                        <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_116117_TERMINSERVICE_Vermittlungscode" />
                        <value value="XN6P-F4HP-Z5KX" />
                    </identifier>
                </basedOn>
                <participant>
                    <actor>
                        <reference value="urn:uuid:10e0c862-0ed4-4a91-93e7-56b858b43da6" />
                    </actor>
                    <status value="accepted" />
                </participant>
                <participant>
                    <actor>
                        <reference value="urn:uuid:f28714b1-627d-426e-88ae-e348076d9738" />
                    </actor>
                    <status value="accepted" />
                </participant>
            </Appointment>
        </resource>
        <search>
            <mode value="include" />
        </search>
    </entry>
</Bundle>

<OperationOutcome xmlns="http://hl7.org/fhir">
    <id value="cc8e9f90-31ad-4021-9639-e5b940a88a94" />
    <meta>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_OperationOutcome_Error|0.2.0" />
    </meta>
    <text>
        <status value="extensions" />
        --- We have skipped the narrative for better readability of the resource ---
    </text>
    <issue>
        <severity value="fatal" />
        <code value="value" />
        <details>
            <coding>
                <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Errors" />
                <code value="TVSTS0000" />
                <display value="Sonstiger Fehler. Unter diagnostics finden Sie n&#228;here Informationen zum Fehler." />
            </coding>
        </details>
        <diagnostics value="Ung&#252;ltiger Input-Parameter" />
    </issue>
</OperationOutcome>

<OperationOutcome xmlns="http://hl7.org/fhir">
    <id value="81758936-362c-411f-9d95-7fac5b19deb6" />
    <meta>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_OperationOutcome_Error|0.2.0" />
    </meta>
    <text>
        <status value="extensions" />
        --- We have skipped the narrative for better readability of the resource ---
    </text>
    <issue>
        <severity value="fatal" />
        <code value="value" />
        <details>
            <coding>
                <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Errors" />
                <code value="TVSTS0018" />
                <display value="Die Dringlichkeit ist ung&#252;ltig." />
            </coding>
        </details>
    </issue>
</OperationOutcome>