SHAPTH
Use Case
qualityReports · qualityReportById · download/report

Prüfbericht herunterladen

Der Download eines Prüfberichts erfolgt in mehreren Schritten: Zuerst wird der r-Wert des gewünschten Akteurs ermittelt. Anschließend wird über GraphQL der Prüfbericht 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 selber zusammengesetzt.

Berechtigung
rollen- und kontextabhängiger Zugriff auf Prüfberichte
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

SchrittZweckEndpointErgebnis
r über GraphQL list/byId des jeweiligen Akteurs ermittelnDen r-Wert abrufen, der bei qualityReports in den Variablen übergeben werden muss.POST /api/graphql/serviceAkteurbezogener r-Wert.
qualityReportsPrüfberichte als Liste abrufen und den passenden Bericht anhand von Titel, Status, Zeitpunkt oder ID finden.POST /api/graphql/serviceListe unter data.qualityReports.items, inklusive id und url.
qualityReportByIdOptionaler Detailabruf: Alternativ zur Listenabfrage einen einzelnen Prüfbericht anhand einer bekannten id abrufen.POST /api/graphql/serviceDetailobjekt unter data.qualityReportById, inklusive aktueller url.
GET report?u=...Die von SHAPTH zurückgegebene Download-URL abrufen.GET /api/v1/download/report?u=...XML-Datei des Prüfberichts.

r-Wert, URL und Download-Token ermitteln GraphQL liefert beim Prüfbericht-Download nicht die XML-Datei selbst, sondern die Metadaten des Prüfberichts. 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?

SituationEmpfohlene AbfrageWarum
Der gewünschte Prüfbericht soll aus einer Trefferliste ausgewählt werden.qualityReportsDie 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 Prüfbericht-ID ist bereits bekannt.qualityReportByIdDie Detailabfrage lädt gezielt genau diesen Bericht und liefert die aktuelle url, ohne zuerst eine Liste filtern zu müssen.
Eine gespeicherte URL soll später erneut verwendet werden.qualityReportByIdDie Download-URL kann kontext- oder zeitbezogen sein. Wenn die ID bekannt ist, sollte die URL vor dem Download frisch über die Detailabfrage ermittelt werden.

qualityReports

qualityReports eignet sich, um vorhandene Prüfberichte 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. Ob Prüfberichte sichtbar sind, hängt zusätzlich von der Rolle, dem fachlichen Kontext und den in SHAPTH hinterlegten Zugriffsrechten ab.

Parameter und Rückgabefelder

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

FeldDetails
input
SchemaNullable
TypQualityReportListInput
Eingabeobjekt für Kontext, Filter und Sortierung der Prüfberichtliste.
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 Prüfberichte.
page
SchemaNullable
TypInt
Seitenindex der Trefferliste.
input
sort
SchemaNullable
TypQualityReportSort
Sortierung der Trefferliste.
input.sort
by
SchemaNullable
TypQualityReportSortField
Sortierfeld, im Beispiel `TITLE`.
order
SchemaNullable
TypOrdering
Sortierreihenfolge, im Beispiel `DESC`.
scope
SchemaNon-null
TypQualityReportScope!

Gibt an, aus welcher fachlichen Rolle die Prüfberichte abgefragt werden.

HDP: Gesundheitsamt
LAB: Zugelassene Untersuchungsstellen
WSP: Wasserversorger
items
id
SchemaNullable
TypQualityReportId
Eindeutige ID des Prüfberichts. Diese ID kann für `qualityReportById` verwendet werden.
title
SchemaNon-null
TypString!
Titel des Prüfberichts.
sent
SchemaNon-null
TypBoolean!
Gibt an, ob der Prüfbericht versendet wurde.
status
SchemaNullable
TypString
Status des Prüfberichts, sofern zurückgegeben.
url
SchemaNullable
TypString
Von SHAPTH erzeugte Download-URL. Der enthaltene Parameter `u` wird für den REST-Dateiabruf übernommen.
uploadedAt
SchemaNon-null
TypDateTime!
Zeitpunkt des Uploads.
receivedAt
SchemaNullable
TypDateTime
Zeitpunkt des Eingangs.
sentAt
SchemaNullable
TypDateTime
Zeitpunkt des Versands.
timeOfValidation
SchemaNullable
TypDateTime
Zeitpunkt der Validierung.
timeOfTransmission
SchemaNullable
TypDateTime
Zeitpunkt der Übermittlung.
items.lab
id
SchemaNullable
TypID
ID des zugeordneten Labors, sofern im Ergebnis enthalten.
name
SchemaNullable
TypString
Name des zugeordneten Labors.
items.cst
id
SchemaNullable
TypID
ID des Betreibers, sofern im Ergebnis enthalten. Das Feld ist ein Rückgabewert und wird nicht für den Download eingegeben.
name
SchemaNullable
TypString
Name des Betreibers.
items
hdp
SchemaNon-null
Typ[Named!]!
Zuständige Gesundheitsämter im Kontext des Prüfberichts. Das Feld zeigt, welchen Behörden der Prüfbericht zugeordnet ist.
items.hdp
id
SchemaNullable
TypID
ID einer zugeordneten Behörde.
name
SchemaNullable
TypString
Name einer zugeordneten Behörde.
items
evaluation
SchemaNullable
TypString
Bewertung oder fachliche Einstufung des Prüfberichts.
orderNr
SchemaNullable
TypString
Auftragsnummer des Prüfberichts.
signed
SchemaNon-null
TypBoolean!
Gibt an, ob der Prüfbericht signiert ist.
limit
SchemaNullable
TypInt
In der Antwort zurückgegebene Seitengröße.
total
SchemaNullable
TypInt
Gesamtzahl der passenden Prüfberichte.
page
SchemaNullable
TypInt
Zurückgegebener Seitenindex.
query QualityReports($input: QualityReportListInput, $scope: QualityReportScope!) {
qualityReports(input: $input, scope: $scope) {
  items {
    title
    sent
    lab { id name __typename }
    cst { id name __typename }
    hdp { id name __typename }
    evaluation
    orderNr
    id
    signed
    status
    url
    uploadedAt
    receivedAt
    sentAt
    timeOfValidation
    timeOfTransmission
  }
  limit
  total
  page
}
}
{
"input": {
  "context": {
    "organization": "<r>"
  },
  "filter": {
    "limit": 10,
    "page": 0
  },
  "sort": {
    "by": "TITLE",
    "order": "DESC"
  }
},
"scope": "LAB"
}
{
"data": {
  "qualityReports": {
    "items": [
      {
        "title": "Pruefbericht Beispiel",
        "sent": true,
        "lab": {
          "id": "<LABORATORY_ID>",
          "name": "Beispiel Labor",
          "__typename": "Named"
        },
        "cst": {
          "id": "<WATER_SUPPLIER_ID>",
          "name": "Beispiel Betreiber",
          "__typename": "Named"
        },
        "hdp": [
          {
            "id": "<AUTHORITY_ID>",
            "name": "Beispiel Gesundheitsamt",
            "__typename": "Named"
          }
        ],
        "evaluation": "1010",
        "orderNr": "1234",
        "id": "<QUALITY_REPORT_ID>",
        "signed": false,
        "status": "s",
        "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",
        "timeOfValidation": "2026-02-24T14:36:27+00:00",
        "timeOfTransmission": "2026-02-24T14:36:27+00:00"
      }
    ],
    "limit": 10,
    "total": 1,
    "page": 0
  }
}
}

qualityReportById

qualityReportById wird verwendet, wenn die ID des Prüfberichts 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 Prüfbericht. Der vorherige Schritt zur Ermittlung und Zuordnung des r-Werts entfällt dadurch nicht.

Parameter und Rückgabefelder

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

FeldDetails
id
SchemaNon-null
TypQualityReportId!
ID des Prüfberichts, zum Beispiel aus `qualityReports.items.id`.
scope
SchemaNon-null
TypQualityReportScope!

Gibt an, aus welcher fachlichen Rolle der Prüfbericht abgefragt wird.

HDP: Gesundheitsamt
LAB: Zugelassene Untersuchungsstellen
WSP: Wasserversorger
qualityReportById
id
SchemaNullable
TypQualityReportId
Eindeutige ID des Prüfberichts.
sent
SchemaNon-null
TypBoolean!
Gibt an, ob der Prüfbericht versendet wurde.
status
SchemaNullable
TypString
Status des Prüfberichts, sofern zurückgegeben.
url
SchemaNullable
TypString
Aktuelle Download-URL mit serverseitig erzeugtem `u`-Parameter.
title
SchemaNon-null
TypString!
Titel des Prüfberichts.
uploadedAt
SchemaNon-null
TypDateTime!
Zeitpunkt des Uploads.
receivedAt
SchemaNullable
TypDateTime
Zeitpunkt des Eingangs.
sentAt
SchemaNullable
TypDateTime
Zeitpunkt des Versands.
query QualityReportById($id: QualityReportId!, $scope: QualityReportScope!) {
qualityReportById(id: $id, scope: $scope) {
  id
  sent
  status
  url
  title
  uploadedAt
  receivedAt
  sentAt
}
}
{
"id": "<DUMMY-SHAPTH-ID>",
"scope": "LAB"
}
{
"data": {
  "qualityReportById": {
    "id": "<QUALITY_REPORT_ID>",
    "sent": true,
    "status": "s",
    "url": "https://pre.api.shapth.de/api/v1/download/report?u=<DOWNLOAD_TOKEN>",
    "title": "Pruefbericht 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 `qualityReports.items.url` oder `qualityReportById.url`.
u
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 Prüfbericht gespeichert wird.
URL-Beispiel
https://pre.api.shapth.de/api/v1/download/report?u=<DOWNLOAD_TOKEN>

On this page

AblaufWelche Abfrage wann?qualityReportsqualityReportByIdDatei herunterladen