Untersuchungsplan herunterladen

monitoringPlans · monitoringPlanById · download/report

Untersuchungsplan herunterladen

Der Download eines Untersuchungsplans erfolgt in mehreren Schritten: Zuerst wird der r-Wert des gewünschten Akteurs ermittelt. Anschließend wird über GraphQL der Untersuchungsplan gesucht oder per ID geladen. Die GraphQL-Antwort enthält im Feld url eine von SHAPTH erzeugte Download-URL mit dem Parameter u. Die XML-Datei selbst wird anschließend nicht über GraphQL übertragen, sondern per REST-GET gegen genau diese zurückgegebene URL heruntergeladen. Der Wert von u wird serverseitig erzeugt und nicht selbst zusammengesetzt.

Berechtigung

rollen- und kontextabhängiger Zugriff auf Untersuchungspläne

GraphQL: URL ermitteln

POST

/api/graphql/service

Weitere Informationen zu Basis-URLs und Umgebungen stehen im Kapitel Endpunkte.

REST: XML-Datei laden

GET

/api/v1/download/report?u=...

Playground(nur GraphQL)

PRE

Ablauf

Schritt	Zweck	Endpoint	Ergebnis
`r` über GraphQL `list`/`byId` des jeweiligen Akteurs ermitteln	Den `r`-Wert abrufen, der bei `monitoringPlans` in den Variablen übergeben werden muss.	`POST /api/graphql/service`	Akteurbezogener `r`-Wert.
`monitoringPlans`	Untersuchungspläne als Liste abrufen und den passenden Plan anhand von Titel, Status, Zeitpunkt oder ID finden.	`POST /api/graphql/service`	Liste unter `data.monitoringPlans.items`, inklusive `id` und `url`.
`monitoringPlanById`	Optionaler Detailabruf: Alternativ zur Listenabfrage einen einzelnen Untersuchungsplan anhand einer bekannten `id` abrufen.	`POST /api/graphql/service`	Detailobjekt unter `data.monitoringPlanById`, inklusive aktueller `url`.
`GET report?u=...`	Die von SHAPTH zurückgegebene Download-URL abrufen.	`GET /api/v1/download/report?u=...`	XML-Datei des Untersuchungsplans.

r-Wert, URL und Download-Token ermitteln GraphQL liefert beim Untersuchungsplan-Download nicht die XML-Datei selbst, sondern die Metadaten des Untersuchungsplans. Vor der Abfrage wird der r-Wert des gewünschten Akteurs ermittelt und im input.context gesetzt: Beginnt r mit R, wird der Wert als institution übergeben. Beginnt r mit T, wird der Wert als organization übergeben. Entscheidend ist anschließend das Feld url. Diese URL enthält den serverseitig erzeugten Wert u. Erst mit dieser URL wird der REST-Download ausgeführt.

Welche Abfrage wann?

Situation	Empfohlene Abfrage	Warum
Der gewünschte Untersuchungsplan soll aus einer Trefferliste ausgewählt werden.	`monitoringPlans`	Die Listenabfrage liefert bereits `id`, Status, Zeitpunkte und die `url`. Wenn der passende Treffer eindeutig ist, kann die URL direkt für den REST-Download verwendet werden.
Die Untersuchungsplan-ID ist bereits bekannt.	`monitoringPlanById`	Die Detailabfrage lädt gezielt genau diesen Untersuchungsplan und liefert die aktuelle `url`, ohne zuerst eine Liste filtern zu müssen.
Eine gespeicherte URL soll später erneut verwendet werden.	`monitoringPlanById`	Die Download-URL kann kontext- oder zeitbezogen sein. Wenn die ID bekannt ist, sollte die URL vor dem Download frisch über die Detailabfrage ermittelt werden.

monitoringPlans

monitoringPlans eignet sich, um vorhandene Untersuchungspläne zu suchen und die passende id oder direkt die url für den Download zu ermitteln. Der Zugriff wird über den scope und den im input.context gesetzten r-Wert gesteuert. Der scope richtet sich nach der fachlichen Rolle: LAB für Labore, WSP für Wasserversorger und HDP für Behörden.

Parameter und Rückgabefelder

Die folgende Feldliste beschreibt die im Beispiel verwendeten Eingaben sowie die wichtigsten Rückgabefelder der Trefferliste.

FeldDetails

input

SchemaNullable

TypMonitoringPlanListInput

Eingabeobjekt für Kontext, Filter und Sortierung der Untersuchungsplanliste.

input

context

SchemaNullable

TypOrganizationOrInstitution

GraphQL-Kontextobjekt, in dem der akteurbezogene r-Wert übergeben wird.

input.context

institution

SchemaNullable

TypInstitutionId

Zu verwenden, wenn der r-Wert mit `R` beginnt.

organization

SchemaNullable

TypOrganizationId

Zu verwenden, wenn der r-Wert mit `T` beginnt.

input

filter

SchemaNullable

TypListFilter

Steuerung der Trefferliste.

input.filter

limit

SchemaNullable

TypInt

Maximale Anzahl der zurückgegebenen Untersuchungspläne.

page

SchemaNullable

TypInt

Seitenindex der Trefferliste.

input

sort

SchemaNullable

TypMonitoringPlanSort

Sortierung der Trefferliste.

input.sort

SchemaNullable

TypMonitoringPlanSortField

Sortierfeld, im Beispiel `TITLE`.

order

SchemaNullable

TypOrdering

Sortierreihenfolge, im Beispiel `DESC`.

scope

SchemaNon-null

TypMonitoringPlanScope!

Gibt an, aus welcher fachlichen Rolle die Untersuchungspläne abgefragt werden.

HDP: Gesundheitsamt

LAB: Zugelassene Untersuchungsstellen

WSP: Wasserversorger

items

SchemaNullable

TypMonitoringPlanId

Eindeutige ID des Untersuchungsplans. Diese ID kann für `monitoringPlanById` verwendet werden.

title

SchemaNon-null

TypString!

Titel des Untersuchungsplans.

status

SchemaNullable

TypString

XWasser-Code für den Status des Untersuchungsplans. Die Werte stehen unten im Abschnitt XWasser-Codes.

url

SchemaNullable

TypString

Von SHAPTH erzeugte Download-URL. Der enthaltene Parameter `u` wird für den REST-Dateiabruf übernommen.

uploadedAt

SchemaNullable

TypDateTime

Zeitpunkt des Uploads.

receivedAt

SchemaNullable

TypDateTime

Zeitpunkt des Eingangs.

sentAt

SchemaNullable

TypDateTime

Zeitpunkt des Versands.

hdp

SchemaNullable

Typ[Named!]

Zugeordnete zuständige Behörden beziehungsweise Gesundheitsämter im Kontext des Untersuchungsplans.

wsp

SchemaNullable

TypNamed

Zugeordneter Wasserversorger beziehungsweise Betreiber im Kontext des Untersuchungsplans.

limit

SchemaNullable

TypInt

In der Antwort zurückgegebene Seitengröße.

total

SchemaNullable

TypInt

Gesamtzahl der passenden Untersuchungspläne.

page

SchemaNullable

TypInt

Zurückgegebener Seitenindex.

AnfrageVariablenResponse

query monitoringPlans($input: MonitoringPlanListInput, $scope: MonitoringPlanScope!) {
monitoringPlans(input: $input, scope: $scope) {
  items {
    id
    title
    status
    url
    uploadedAt
    receivedAt
    sentAt
    hdp { id name __typename }
    wsp { id name __typename }
  }
  limit
  total
  page
}
}

{
"input": {
  "context": {
    "organization": "<r>"
  },
  "filter": {
    "limit": 10,
    "page": 0
  },
  "sort": {
    "by": "TITLE",
    "order": "DESC"
  }
},
"scope": "HDP"
}

{
"data": {
  "monitoringPlans": {
    "items": [
      {
        "id": "<MONITORING_PLAN_ID>",
        "title": "Untersuchungsplan Beispiel",
        "status": "1061",
        "url": "https://pre.api.shapth.de/api/v1/download/report?u=<DOWNLOAD_TOKEN>",
        "uploadedAt": "2026-05-27T07:37:38.125+00:00",
        "receivedAt": "2026-05-27T07:37:38.125+00:00",
        "sentAt": "2026-05-27T07:37:38.125+00:00",
        "hdp": [
          {
            "id": "<AUTHORITY_ID>",
            "name": "Beispiel Gesundheitsamt",
            "__typename": "Named"
          }
        ],
        "wsp": {
          "id": "<WATER_SUPPLIER_ID>",
          "name": "Beispiel Betreiber",
          "__typename": "Named"
        }
      }
    ],
    "limit": 10,
    "total": 1,
    "page": 0
  }
}
}

monitoringPlanById

monitoringPlanById wird verwendet, wenn die ID des Untersuchungsplans bereits bekannt ist oder aus der zuvor mit input.context abgefragten Liste übernommen wurde. Auch diese Abfrage liefert nicht die XML-Datei selbst, sondern die aktuelle Download-URL für genau diesen Untersuchungsplan. Der vorherige Schritt zur Ermittlung und Zuordnung des r-Werts entfällt dadurch nicht.

Parameter und Rückgabefelder

Für die Detailabfrage werden die Untersuchungsplan-ID und der fachliche Scope benötigt. Die wichtigsten Rückgabefelder entsprechen der Listenabfrage.

FeldDetails

SchemaNon-null

TypMonitoringPlanId!

ID des Untersuchungsplans, zum Beispiel aus `monitoringPlans.items.id`.

scope

SchemaNon-null

TypMonitoringPlanScope!

Gibt an, aus welcher fachlichen Rolle der Untersuchungsplan abgefragt wird.

HDP: Gesundheitsamt

LAB: Zugelassene Untersuchungsstellen

WSP: Wasserversorger

monitoringPlanById

SchemaNullable

TypMonitoringPlanId

Eindeutige ID des Untersuchungsplans.

status

SchemaNullable

TypString

XWasser-Code für den Status des Untersuchungsplans. Die Werte stehen unten im Abschnitt XWasser-Codes.

url

SchemaNullable

TypString

Aktuelle Download-URL mit serverseitig erzeugtem `u`-Parameter.

title

SchemaNon-null

TypString!

Titel des Untersuchungsplans.

uploadedAt

SchemaNullable

TypDateTime

Zeitpunkt des Uploads.

receivedAt

SchemaNullable

TypDateTime

Zeitpunkt des Eingangs.

sentAt

SchemaNullable

TypDateTime

Zeitpunkt des Versands.

AnfrageVariablenResponse

query monitoringPlanById($id: MonitoringPlanId!, $scope: MonitoringPlanScope!) {
monitoringPlanById(id: $id, scope: $scope) {
  id
  status
  url
  title
  uploadedAt
  receivedAt
  sentAt
}
}

{
"id": "<DUMMY-SHAPTH-ID>",
"scope": "HDP"
}

{
"data": {
  "monitoringPlanById": {
    "id": "<MONITORING_PLAN_ID>",
    "status": "1061",
    "url": "https://pre.api.shapth.de/api/v1/download/report?u=<DOWNLOAD_TOKEN>",
    "title": "Untersuchungsplan Beispiel",
    "uploadedAt": "2026-05-27T07:37:38.125+00:00",
    "receivedAt": "2026-05-27T07:37:38.125+00:00",
    "sentAt": "2026-05-27T07:37:38.125+00:00"
  }
}
}

Datei herunterladen

Die Datei wird über die in url zurückgegebene Download-URL abgerufen. Der enthaltene u-Parameter ist ein von SHAPTH erzeugter Download-Wert und wird unverändert übernommen.

Download-Parameter

Für den Dateiabruf wird keine eigene GraphQL-Query mehr benötigt. Es wird die zuvor ermittelte URL per REST-GET verwendet.

FeldDetails

url

SchemaNon-null

TypString!

Vollständige Download-URL aus `monitoringPlans.items.url` oder `monitoringPlanById.url`.

SchemaNon-null

TypString!

Serverseitig erzeugter Download-Wert innerhalb der URL. Dieser Wert wird nicht selbst generiert.

output

SchemaNon-null

TypXML-Datei

Zieldatei, in die der Untersuchungsplan gespeichert wird.

URL-Beispiel

https://pre.api.shapth.de/api/v1/download/report?u=<DOWNLOAD_TOKEN>

XWasser-Codes

Status des Untersuchungsplans

Verwendete Version: Status Untersuchungsplan_2.xml · Hinweis: Ggf. aktuelle Codeliste im XRepository öffnen.

Code	Status	Beschreibung
`1010`	In Erstellung	Der Untersuchungsplan befindet sich in Erstellung.
`1020`	Bei GA angefragt	Der Untersuchungsplan wurde beim Gesundheitsamt angefragt.
`1031`	Bei Betreiber angefragt	Der Untersuchungsplan wurde beim Betreiber angefragt.
`1041`	Durch Betreiber zu vervollständigen	Der Untersuchungsplan ist durch den Betreiber zu vervollständigen.
`1050`	Abgelehnt	Der Untersuchungsplan wurde abgelehnt.
`1061`	Freigegeben	Der Untersuchungsplan ist freigegeben.

GraphQL-Enums

Die folgenden GraphQL-Enums werden in den Beispielvariablen verwendet.

Enum	Wert	Bedeutung
`MonitoringPlanScope`	`LAB`	Untersuchungspläne im Kontext eines Labors beziehungsweise einer zugelassenen Untersuchungsstelle.
`MonitoringPlanScope`	`HDP`	Untersuchungspläne im Kontext einer zuständigen Behörde beziehungsweise eines Gesundheitsamts.
`MonitoringPlanScope`	`WSP`	Untersuchungspläne im Kontext eines Wasserversorgers beziehungsweise Betreibers.
`MonitoringPlanSortField`	`TITLE`	Sortierung nach Titel des Untersuchungsplans.
`MonitoringPlanSortField`	`STATUS`	Sortierung nach Statusfeld.
`MonitoringPlanSortField`	`UPLOADED_AT`	Sortierung nach Upload-Zeitpunkt.
`MonitoringPlanSortField`	`RECEIVED_AT`	Sortierung nach Eingangszeitpunkt.
`MonitoringPlanSortField`	`SENT_AT`	Sortierung nach Versandzeitpunkt.
`Ordering`	`ASC`	Aufsteigende Sortierung.
`Ordering`	`DESC`	Absteigende Sortierung.