/api/v1/xwasser/v100

Der Prüfbericht wird als XWasser-Nachricht des Typs 2010 über den versionierten REST-Endpunkt übertragen. Vor dem Versand müssen die technischen Kopfwerte und die fachlichen Angaben im XML zum konkreten Testfall passen.

Allgemeiner Aufbau einer XWasser-Nachricht (Prüfbericht)

Der folgende Teil erläutert den grundsätzlichen XML-Aufbau einer XWasser-konformen Nachricht, die einen Prüfbericht enthält. Sie richtet sich an Software-Hersteller, die Prüfberichte über die SHAPTH-Schnittstelle erzeugen und übermitteln möchten. Es werden nachfolgend nicht alle Attribute des Prüfberichts beschrieben. Maßgeblich hierfür bleiben die XWasser-Spezifikation, die XML-Schema-Dateien und die XWasser-Codelisten. Ziel dieser Seite ist es, die übergeordnete Nachrichtenstruktur verständlich zu machen und die wichtigsten Strukturebenen einer Nachricht, die einen Prüfbericht enthält, einzuordnen.

Grundprinzip

Ein Prüfbericht wird in XWasser nicht als isoliertes XML-Fragment übermittelt. Er ist Teil einer vollständigen XWasser-Nachricht.

Die Nachricht besteht vereinfacht aus:

<xwas:vorgang.transportieren.2010>
<nachrichtenkopf.g2g>
  ...
</nachrichtenkopf.g2g>
<xwas:vorgang>
  ...
  <xwas:vorgangType>
    <xwas:pruefbericht>
      ...
    </xwas:pruefbericht>
  </xwas:vorgangType>
</xwas:vorgang>
</xwas:vorgang.transportieren.2010>

Die XWasser-Nachricht zur Übermittlung eines Prüfberichts lässt sich vereinfacht in drei zentrale Ebenen unterteilen:

Wurzelelement: vorgang.transportieren.2010

<xwas:vorgang.transportieren.2010
standard="XWasser"
version="1.0.0">
...
</xwas:vorgang.transportieren.2010>

vorgang.transportieren.2010 wird verwendet, wenn ein neuer fachlicher Vorgang transportiert wird. Der eigentliche fachliche Inhalt kann dabei ein Prüfbericht, ein Untersuchungsplan oder ein OLB-Bericht sein. Bei einer Nachricht zur Übermittlung eines Prüfberichts befindet sich unterhalb des Vorgangs im Element xwas:vorgangType das Element xwas:pruefbericht. Die XWasser-Spezifikation beschreibt vorgangType entsprechend als Auswahlstruktur für Untersuchungsplan, Pruefbericht oder OLB-Bericht.

Wichtige Attribute am Wurzelelement sind insbesondere:

Die XWasser-Version im XML muss zum verwendeten SHAPTH-Endpunkt passen.

Nachrichtenkopf: nachrichtenkopf.g2g

Direkt unterhalb des Wurzelelements steht der Nachrichtenkopf:

<nachrichtenkopf.g2g>
<identifikation.nachricht>
  ...
</identifikation.nachricht>
<leser>
  ...
</leser>
<autor>
  ...
</autor>
</nachrichtenkopf.g2g>

Der Nachrichtenkopf beschreibt die Nachricht selbst. Er enthält insbesondere Informationen zur eindeutigen Identifikation der Nachricht, zum fachlichen Absender und Empfänger sowie optional weitere technische Angaben für den Transportkontext:

Der Nachrichtenkopf ist nicht der Prüfbericht. Er enthält Metadaten zur Nachricht und zur fachlichen Adressierung.

Innerhalb des Nachrichtenkopfs befindet sich die identifikation.nachricht:

<identifikation.nachricht>
<nachrichtenUUID>c3312556-d42d-48e1-a66e-6a3a7a65e24f</nachrichtenUUID>
<nachrichtentyp>
  <code>2010</code>
</nachrichtentyp>
<erstellungszeitpunkt>2026-03-01T15:00:00</erstellungszeitpunkt>
</identifikation.nachricht>

Die drei zentralen Angaben sind:

Die nachrichtenUUID ist für die Nachricht selbst vorgesehen. Sie ist nicht identisch mit der Vorgangs-ID und nicht identisch mit der Prüfbericht-UUID.

Im Nachrichtenkopf werden außerdem Autor und Leser angegeben.

<leser>
<verzeichnisdienst listVersionID="3" listURI="urn:xoev-de:kosit:codeliste:verzeichnisdienst">
  <code>DVDV</code>
</verzeichnisdienst>
<kennung>ghb:<DUMMY-SHAPTH-ID></kennung>
<name>Beispiel Gesundheitsamt</name>
</leser>
<autor>
<verzeichnisdienst listVersionID="3" listURI="urn:xoev-de:kosit:codeliste:verzeichnisdienst">
  <code>DVDV</code>
</verzeichnisdienst>
<kennung>lab:<DUMMY-SHAPTH-ID></kennung>
<name>Beispiel Labor</name>
</autor>

Bei der Prüfberichtübermittlung gilt typischerweise:

Für die Kennung wird das fachliche Präfix vor die jeweilige SHAPTH-ID gesetzt:

Die Angaben im Nachrichtenkopf müssen zur fachlichen Situation passen. Insbesondere sollte der Autor im Nachrichtenkopf zur im Prüfbericht angegebenen Untersuchungsstelle passen.

Vorgang: xwas:vorgang

Nach dem Nachrichtenkopf folgt der fachliche Vorgang:

<xwas:vorgang>
<xwas:identifikationVorgang>
  <xwas:vorgangsID>...</xwas:vorgangsID>
</xwas:identifikationVorgang>
<xwas:vorgangType>
  <xwas:pruefbericht>
    ...
  </xwas:pruefbericht>
</xwas:vorgangType>
</xwas:vorgang>

Der Vorgang bildet die fachliche Klammer um den übermittelten Inhalt.

Wichtig ist die Unterscheidung zwischen Nachricht und Vorgang:

Ein Vorgang kann im weiteren Verlauf mehrere Nachrichten umfassen. Die Vorgangs-ID ist daher nicht mit der Nachrichten-UUID gleichzusetzen.

Innerhalb des Vorgangs befindet sich der Vorgangstyp:

<xwas:vorgangType>
<xwas:pruefbericht>
  ...
</xwas:pruefbericht>
</xwas:vorgangType>

vorgangType ist die Stelle, an der der konkrete fachliche Inhalt der Vorgangsnachricht eingehängt wird.

Für Prüfberichte ist hier das Element xwas:pruefbericht zu verwenden.

Andere Vorgangstypen, z. B. Untersuchungsplan oder OLB-Bericht, werden an dieser Stelle nicht verwendet, wenn eine Nachricht zur Übermittlung eines Prüfberichts erzeugt werden soll.

Der Prüfbericht selbst befindet sich unterhalb von:

<xwas:vorgang>
<xwas:vorgangType>
  <xwas:pruefbericht>
    ...
  </xwas:pruefbericht>
</xwas:vorgangType>
</xwas:vorgang>

Der Prüfbericht enthält die fachlichen Inhalte, insbesondere Angaben zu:

Hier werden die fachlichen Einzelfelder im Prüfbericht-Body nicht vollständig beschrieben. Für die konkrete Befüllung der einzelnen Prüfberichtfelder sind die XWasser-Spezifikation, die XSDs, Codelisten und Business Rules maßgeblich.

Für die strukturelle Einordnung ist entscheidend, dass der Prüfbericht nicht der Nachrichtenkopf, sondern der fachliche Inhalt des Vorgangs ist.

Optionale Anlagen

Anlagen werden nicht im Nachrichtenkopf, sondern im Vorgang abgebildet.

<xwas:vorgang>
...
<xwas:anlage dokumentID="anhang1">
  ...
</xwas:anlage>
</xwas:vorgang>

Wenn im Prüfbericht oder in einer Probe auf einen Anhang verwiesen wird, muss ein dazu passender Anlagenblock mit entsprechender dokumentID vorhanden sein. Wenn kein Anhang übermittelt werden soll, sollten weder Anhangreferenzen noch verwaiste Anlagenblöcke enthalten sein.

Optionale Signatur

XWasser sieht die Möglichkeit vor, Nachrichten oder Nachrichtenteile zu signieren. Die Signatur ist strukturell von der fachlichen Prüfberichtbefüllung zu unterscheiden.

Die Signatur dient insbesondere dem Nachweis der Integrität und der Autorenschaft bzw. Zuordnung des signierten Inhalts. Ob und wie eine Signatur zu verwenden ist, richtet sich nach den Vorgaben der XWasser-Spezifikation und den SHAPTH-spezifischen Anforderungen. Nach der Signatur darf der signierte Inhalt nicht mehr verändert werden, da die Signatur sonst ungültig wird.

Strukturübersicht

Die folgende Übersicht fasst die zuvor beschriebenen Strukturebenen einer Nachricht zur Übermittlung eines Prüfberichts zusammen:

<xwas:vorgang.transportieren.2010>
|
+-- <nachrichtenkopf.g2g>
|   |
|   +-- <identifikation.nachricht>
|   |   +-- <nachrichtenUUID>
|   |   +-- <nachrichtentyp>
|   |   +-- <erstellungszeitpunkt>
|   |
|   +-- <leser>
|   |   +-- <verzeichnisdienst>
|   |   +-- <kennung>
|   |   +-- <name>
|   |
|   +-- <autor>
|       +-- <verzeichnisdienst>
|       +-- <kennung>
|       +-- <name>
|
+-- <xwas:vorgang>
  |
  +-- <xwas:identifikationVorgang>
  |   +-- <xwas:vorgangsID>
  |
  +-- <xwas:vorgangType>
  |   +-- <xwas:pruefbericht>
  |       +-- fachlicher Prüfbericht-Body
  |
  +-- optional: <xwas:bemerkung>
  +-- optional: <xwas:anlage>
  +-- optional: <xwas:erweiterung>

Diese Struktur sollte bei der Erzeugung einer Nachricht zur Übermittlung eines Prüfberichts immer vollständig betrachtet werden. Eine gültige Prüfberichtübermittlung besteht nicht nur aus dem Element xwas:pruefbericht, sondern aus der gesamten XWasser-Nachricht.

Praktische Anpassung der Ausgangsdatei

Überblick

Das verlinkte Minimalbeispiel ist eine Ausgangsdatei. Es zeigt die Struktur eines Prüfberichts unter xwas:vorgang > xwas:vorgangType > xwas:pruefbericht, enthält aber noch Werte, die vor dem Senden angepasst werden müssen.

Schrittweise Herangehensweise zum Erstellen und Hochladen des Prüfbericht-Minimalbeispiels

<identifikation.nachricht>
<nachrichtenUUID>693c64d6-456f-4d14-abe7-fe9681c74abd</nachrichtenUUID>
...
</identifikation.nachricht>

<leser>
<verzeichnisdienst listVersionID="">
  <code></code>
</verzeichnisdienst>
<kennung>ghb:<DUMMY-SHAPTH-ID></kennung>
<name>Beispiel Gesundheitsamt</name>
</leser>
<autor>
<verzeichnisdienst listVersionID="">
  <code></code>
</verzeichnisdienst>
<kennung>lab:<DUMMY-SHAPTH-ID></kennung>
<name>API Doku Lab</name>
</autor>

<xwas:anhang>anhang1</xwas:anhang>

<xwas:anlage dokumentID="anhang1">
<xwas:dokumentTyp listURI="urn:xoev-de:xwasser:codeliste:dokumenttyp" listVersionID="1">
  <code>1010</code>
</xwas:dokumentTyp>
<xwas:name>Anlage 1</xwas:name>
<xwas:dokumentRepraesentation dokumentRepraesentationID="doc1">
  <xwas:mimeType>application/pdf</xwas:mimeType>
  <xwas:dateiname>Test.pdf</xwas:dateiname>
  <xwas:inhaltTyp>pdf</xwas:inhaltTyp>
</xwas:dokumentRepraesentation>
</xwas:anlage>

<xwas:auftraggeber>
<xwas:auftraggeberID><DUMMY-SHAPTH-ID></xwas:auftraggeberID>
...
</xwas:auftraggeber>

<xwas:beauftragteUntersuchungsstelle>
...
<xwas:zugelasseneUntersuchungsstelleID><DUMMY-SHAPTH-ID></xwas:zugelasseneUntersuchungsstelleID>
</xwas:beauftragteUntersuchungsstelle>

<!-- Vor dem Versand keine DUMMY-Werte im XML belassen -->
<xwas:name>API Doku Lab</xwas:name>
<xwas:auftraggeberID><DUMMY-SHAPTH-ID></xwas:auftraggeberID>

# 1) Access Token abrufen
TOKEN=$(curl -s \
-d "client_id=<CLIENT_ID>" \
-d "client_secret=<CLIENT_SECRET>" \
-d "grant_type=client_credentials" \
"https://pre.id.shapth.de/realms/shapth/protocol/openid-connect/token" | jq -r .access_token)

# 2) Prüfbericht (XML) hochladen
curl -i -X POST "https://pre.www.shapth.de/api/v1/xwasser/v100" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/xml;charset=utf-8" \
-H "Accept: application/xml" \
--data-binary @/Pfad/zu/pruefbericht.xml

#[derive(Parser)]
struct SendCommand {
/// Client id.
#[arg(long, env)]
client_id: String,
/// Client secret.
#[arg(long, env)]
client_secret: String,
/// Authorization endpoint.
#[arg(
  long,
  env,
  default_value = "https://pre.id.shapth.de/realms/shapth/protocol/openid-connect/token"
)]
token_url: String,
/// xWasser endpoint (REST, XML).
#[arg(
  long,
  env,
  default_value = "https://pre.www.shapth.de/api/v1/xwasser/v100"
)]
api_url: String,
/// Path to XML message.
#[arg(long, env)]
xml: std::path::PathBuf,
}

impl SendCommand {
fn run(&self) -> anyhow::Result<()> {
  let client = reqwest::blocking::Client::new();

  // 1) Access Token abrufen
  let response = client
    .post(&self.token_url)
    .form(&[
      ("client_id", self.client_id.as_str()),
      ("client_secret", self.client_secret.as_str()),
      ("grant_type", "client_credentials"),
    ])
    .send()?;

  #[derive(serde::Deserialize)]
  struct Bearer { access_token: String }

  let bearer: Bearer = check_error(response)?.json()?;

  // 2) XML-Datei laden und hochladen
  let xml = std::fs::read_to_string(&self.xml)?;
  let response = client
    .post(&self.api_url)
    .bearer_auth(bearer.access_token)

Checkliste vor dem Versand

Ein erfolgreicher HTTP-Aufruf bedeutet nicht automatisch, dass der fachliche Vorgang endgültig abgeschlossen ist. Die Einordnung von HTTP-Erfolg, XWasser-Quittungen und fachlicher Annahme ist im allgemeinen Teil unter HTTP-Statuscodes beschrieben.