PractitionerRole abrufen (PractitionerRole Search)

Inhalt

1. Beschreibung und fachlicher Kontext
2. Request
   • Request Header
   • Request Body
     • Suchparameter: ID
     • Suchparameter: Betriebsstättennummer (BSNR)
     • Suchparameter: Arztnummer (ANR)
     • Suchparameter: Anzahl der Suchergebnisse
     • Suchparameter: Seite der Suchergebnisse
   • Beispiele
3. Response
   • Response Header
   • Response Body
   • Beispiele

Beschreibung und fachlicher Kontext

Beim Abrufen von PractitionerRoles handelt es sich um die FHIR-Standardinteraktion search. Diese ermöglicht das Synchronisieren mit dem 116117 Terminservice, um den aktuellen Status einzelner oder mehrerer PractitionerRoles abzurufen.

Die PractitionerRole dient als Verbindung zwischen einer Praxis / medizinischen Einrichtung und einem dort tätigen Arzt. Aufgrund der Einschränkungen der jeweiligen Basisprofile wird in Terminprofilen und Terminbuchungen auf eine PractitionerRole referenziert. Die Referenzierung der Profile untereinander ist auf der Seite FHIR-Ressourcen beschrieben. Dort sind auch die Seiten zu den genannten Profilen verlinkt, unter denen weitere Details zu finden sind.

Das Abrufen der PractitionerRoles ist nur für das Anlegen eines Terminprofils notwendig, da hier die korrekte PractitionerRole-ID angeben werden muss. Details zu dieser Interaktion sind unter Terminprofil anlegen (Schedule Create) zu finden.

Beim Abrufen der PractitionerRoles sind die übertragenen Datenmengen in der Regel gering. Die maximale Anzahl an PractitionerRoles entspricht der Anzahl der in einer Praxis / medizinischen Einrichtung tätigen Ärzte plus einer weiteren PractitionerRole, die keinen Verweis auf einen Arzt enthält. Ruft eine Praxis / medizinische Einrichtung die PractitionerRoles für die Haupt- und alle Nebenbetriebsstätten ab, ist die Anzahl der zurückgegebenen Ressourcen entsprechend die Summe der Anzahl der Ärzte all dieser Betriebsstätten und der Anzahl der Betriebsstätten.

Entsprechend dem FHIR-Standard nutzen die Systeme des 116117 Terminservices paging bzw. page count for search results. Das bedeutet Folgendes:

• Die Suchergebnisse sind in Seiten unterteilt. Ruft ein TVS mehrere PractitionerRoles ab, schicken die Systeme des 116117 Terminservices zunächst die erste Seite der Suchergebnisse zurück, also bspw. die ersten 10 Treffer der Suchergebnisse. In der Antwort (Response) auf die Anfrage des TVS ist auch die Information enthalten, ob es noch weitere Seiten an Suchergebnissen gibt und wie diese abzurufen sind. Ein TVS muss also prüfen, ob es noch eine nächste Seite gibt. Ist dies der Fall, muss das TVS eine weitere Anfrage mit dem entsprechenden Suchparameter an die Systeme des 116117 Terminservices schicken, um auch die nächste Seite der Suchergebnisse zu bekommen.

• Beim Abruf mehrerer PractitionerRoles wird nur eine bestimmte Anzahl an Suchergebnissen zurückgegeben. Die Anzahl der Suchergebnisse hängt von dem entsprechenden Suchparameter sowie davon ab, wie viele Suchergebnisse die Systeme des 116117 Terminservices insgesamt gefunden haben.

Request

Das Abrufen von PractitionerRoles erfordert einen POST-Request. Es können entweder alle PractitionerRoles aller autorisierten Einrichtungen oder nur bestimmte PractitionerRoles anhand entsprechender Suchparameter im Request Body abgefragt werden (siehe hierzu Abschnitt Request Body).

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 oben 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.

Request Header

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

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. Das bedeutet, dass die Systeme des 116117 Terminservice diese Suchparameter nicht verarbeiten. Es wird in diesem Fall kein Fehler geworfen; die Suche wird ohne die unbekannten Suchparameter durchgeführt.

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: ID

Suchparameter: Betriebsstättennummer (BSNR)

Suchparameter: Arztnummer (ANR)

Suchparameter: Anzahl der Suchergebnisse

Suchparameter: Seite der Suchergebnisse

¹ 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.

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

Beispiele

Beispiel 1: Suche anhand einer ANR

# Suche die PractitionerRole, die der ANR 123456789 zugeordnet ist
POST https://terminsynchronisation.eterminservice.kv-safenet.de/tvs​/terminsynchronisation/api/PractitionerRole/_search
Content-Type: application/x-www-form-urlencoded
anr=123456789

Beispiel 2: Suche anhand mehrerer IDs

# Suche alle PractitionerRoles, die eine der folgenden IDs haben: 123456789, 123456789-1122334
POST https://terminsynchronisation.eterminservice.kv-safenet.de/tvs​/terminsynchronisation/api/PractitionerRole/_search
Content-Type: application/x-www-form-urlencoded
_id=123456789,123456789-1122334

Beispiel 3: Suche anhand einer BSNR

# Suche alle PractitionerRoles, die der BSNR 123456789 zugeordnet sind
POST https://terminsynchronisation.eterminservice.kv-safenet.de/tvs​/terminsynchronisation/api/PractitionerRole/_search
Content-Type: application/x-www-form-urlencoded
bsnr=123456789

Response

Für die Suche von PractitionerRoles 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 PractitionerRoles, die den Haupt- und Nebenbetriebsstätten der in der Autorisierung übergebenen BSNR zugeordnet sind.

• Wurde bei der Suche min. ein Suchparameter übergeben, enthält dieses Searchset alle PractitionerRoles, 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.

Response Header

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

Response Body

Im Erfolgsfall ist im Response Body ein Searchset Bundle enthalten, welches folgende Ressourcen und Informationen enthält:

• Suchergebnisse als Set: Dieses Set kann auch leer sein, wenn anhand der gesetzten Suchparameter keine passenden PractitionerRoles gefunden werden konnten.

• Alle Suchparameter, die durch die Systeme des 116117 Terminservices verarbeitet und für die Suche genutzt wurden (im Element Bundle.link).

• Verweis auf die vorherige und/oder nächste Seite der Suchergebnisse, wenn vorhanden (im Element Bundle.link).

• In der PractitionerRole referenzierte Ressourcen:

  • Arzt (Practitioner)

Details zum Searchset Bundle sind unter Profil: Suchergebnisse (Bundle) zu finden.

Im Fehlerfall ist im Response Body 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|1.0.0" />
    </meta>
    <type value="searchset" />
    <timestamp value="2024-09-02T12:34:56+02:00" />
    <total value="1" />
    <link>
        <relation value="self" />
        <url value="https://fhir.kbv.de/PractitionerRole?bsnr=123456789&amp;_count=10" />
    </link>
    <entry>
        <fullUrl value="https://fhir.kbv.de/PractitionerRole/123456789-1112223" />
        <resource>
            <PractitionerRole>
                <id value="123456789-1112223" />
                <meta>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_PractitionerRole|1.0.0" />
                </meta>
                <text>
                    <status value="extensions" />
                    <div xmlns="http://www.w3.org/1999/xhtml">Diese PractitionerRole-Instanz enthält die BSNR einer Praxis und die Referenz auf eine Practitioner-Instanz.</div>
                </text>
                <period>
                    <start value="1960-01-25" />
                    <end value="2022-12-10" />
                </period>
                <practitioner>
                    <reference value="urn:uuid:3f03e5bc-f5ba-4017-971d-fd7de95db07c" />
                </practitioner>
                <organization>
                    <identifier>
                        <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_Base_BSNR" />
                        <value value="123456789" />
                    </identifier>
                </organization>
            </PractitionerRole>
        </resource>
        <search>
            <mode value="match" />
        </search>
    </entry>
    <entry>
        <fullUrl value="urn:uuid:3f03e5bc-f5ba-4017-971d-fd7de95db07c" />
        <resource>
            <Practitioner>
                <id value="3f03e5bc-f5ba-4017-971d-fd7de95db07c" />
                <meta>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Practitioner|1.0.0" />
                </meta>
                <text>
                    <status value="extensions" />
                    <div xmlns="http://www.w3.org/1999/xhtml">Diese Practitioner-Instanz beschreibt eine behandelnde Person mit der ANR 111222333</div>
                </text>
                <identifier>
                    <type>
                        <coding>
                            <system value="http://terminology.hl7.org/CodeSystem/v2-0203" />
                            <code value="LANR" />
                            <display value="Lifelong physician number" />
                        </coding>
                    </type>
                    <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_Base_ANR" />
                    <value value="111222333" />
                </identifier>
                <name>
                    <use value="official" />
                    <family value="Mustermensch" />
                    <given value="Michel" />
                </name>
                <qualification>
                    <code>
                        <coding>
                            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAS_FACHGEBIET_GROB" />
                            <code value="09" />
                            <display value="Kinderarzt / Kinder&#228;rztin" />
                        </coding>
                    </code>
                </qualification>
            </Practitioner>
        </resource>
        <search>
            <mode value="include" />
        </search>
    </entry>
</Bundle>

<Bundle xmlns="http://hl7.org/fhir">
    <meta>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Bundle_Searchset|1.0.0" />
    </meta>
    <type value="searchset" />
    <timestamp value="2024-09-02T12:34:56+02:00" />
    <total value="1" />
    <link>
        <relation value="self" />
        <url value="https://fhir.kbv.de/PractitionerRole?_id=123456789&amp;_count=5" />
    </link>
    <entry>
        <fullUrl value="https://fhir.kbv.de/PractitionerRole/123456789" />
        <resource>
            <PractitionerRole>
                <id value="123456789" />
                <meta>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_PractitionerRole|1.0.0" />
                </meta>
                <text>
                    <status value="extensions" />
                    <div xmlns="http://www.w3.org/1999/xhtml">Diese PractitionerRole-Instanz enthält nur die BSNR einer Praxis.</div>
                </text>
                <organization>
                    <identifier>
                        <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_Base_BSNR" />
                        <value value="123456789" />
                    </identifier>
                </organization>
            </PractitionerRole>
        </resource>
        <search>
            <mode value="match" />
        </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|1.0.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|1.0.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>