Begleitschein und Übernahmeschein¶

Diese Anleitung führt einen Begleitschein durch seinen Lebenszyklus: anlegen, füllen, signieren, nächster Layer, an ZEDAL senden. Die REST-Aufrufe stehen unter Über REST, den C#-Code zeigt der SDK-Bereich.

Voraussetzungen: ein Zugang zu ZEDAL (Erste Schritte) und das Arbeitsmodell aus der Übersicht.

Mit dem .NET SDK

Den Code zu dieser Anleitung zeigt BmuDocumentHandler.

Anlegen¶

Aus einem ZEDAL-Muster¶

Muster liegen auf dem ZEDAL-Server, die Liste liefert client.CoreApi.Query.ListTransportTemplates(…). Für BMU zählen diese Felder eines Eintrags:

Feld	Bedeutung
`template_id`	Kennung zum Herunterladen
`interne_bezeichnung`	betriebsinterne Bezeichnung
`art`	`N` = Begleitschein, `S` = Übernahmeschein, `L` = Nachweisliste
`format`	nur `BMU` ist BMU-XML
`anzahl`	Anzahl der Scheine, die aus dem Muster abgerufen werden dürfen

→ Umsetzung mit dem .NET SDK

Aus Daten¶

→ Umsetzung mit dem .NET SDK

VALIDATION_NONE schaltet die Prüfung ab, etwa für einen Entwurf; CreateDocument prüft ohne Optionen vollständig, dann scheitert ein unvollständiger Begleitschein mit CANCELLED. Mit vorlageLayer: true beginnt das Dokument mit einem Vorlagelayer; dann gehört eine Rolle in die Optionen, etwa AtbRolle = Rolle.Erz.

Felder setzen¶

→ Umsetzung mit dem .NET SDK

Nur Felder mit InLayer = true werden geschrieben. Ein Feld ohne die Markierung ignoriert der Dienst, der Aufruf meldet trotzdem Erfolg. Die Kurzkonstruktoren Sf(…) und Df(…) aus ProtoFields setzen die Markierung nicht.
Nicht mitgeschickte Felder bleiben unverändert.
Eine mitgeschickte, nicht leere Liste bestimmt die Länge der Liste im Dokument.
XmlOptions gelten nur für diesen Aufruf. Ohne sie prüft UpdateDocument vollständig.

Formate und Einheiten: Feldregeln → BMU.

Signieren¶

Layer sind über die SignerApi noch nicht signierbar

Eine Signatur an einer bestimmten Signaturstelle eines Layers folgt. Derzeit signiert die SignerApi ein BMU-Dokument als Ganzes, BmuSigningOptions wird nicht ausgewertet. Signaturen, die einen Layer abschließen, sind darüber deshalb noch nicht möglich.

Welche Signaturstellen im aktuellen Layer offen sind, liefert GetValidSignaturePositions.

→ Umsetzung mit dem .NET SDK

Jede Stelle steht zweimal in der Liste, ohne und mit envelope (Signatur über das ganze Dokument).

Signiert wird über den WebSigner (infotech.signer.sign.v1): Vorgang mit dem aktuellen XML anlegen und vorlegen, die signing_url einem Menschen zeigen, der dort signiert, auf den Abschluss warten, Ergebnis abholen. Das Ergebnis enthält das vollständige signierte XML. SignAsync erledigt das in einem Aufruf.

DocumentResults.IsUsable (Namespace Zedal.Sdk.Apis.Signer) prüft, dass das Dokument signiert ist und das Prüfergebnis es nicht verwirft; ein fehlgeschlagenes Dokument hat keinen Inhalt. Wie SignAsync wartet, wie du abbrichst und wie du Vorlegen und Abholen trennst (SubmitAsync, GetSigningProcess, GetResults), steht unter Signieren mit dem SDK.

Nächster Layer¶

→ Umsetzung mit dem .NET SDK

AddLayer funktioniert auch auf einem signierten Begleitschein. Ohne XmlOptions prüft AddLayer den neuen Layer nicht. Ein Ergänzungslayer braucht die Rolle, für die sie angelegt wird, etwa AddLayer(LayerType.Ergaenzung, new XmlOptions { AtbRolle = Rolle.Ent }).

Lesen¶

→ Umsetzung mit dem .NET SDK

Load ruft GetDocument und setzt DocXml und Document. In Document.Meta stehen auch Layer, Signaturen und Signaturstellen. Ein in ZEDAL abgelegtes Dokument lädt LoadTransportDocumentFromZedal(…) über eine Kennung.

An ZEDAL senden¶

→ Umsetzung mit dem .NET SDK

Gesendet wird das gesamte aktuelle DocXml mit allen Layern an DocumentApi.ImportTransportDocument. Gibt es in ZEDAL schon ein Dokument mit derselben Transport-Kennung, entsteht eine neue Version, sonst ein neues Dokument.

Parameter	Wirkung
`distribute`	an die übrigen Beteiligten zustellen (vermitteln), ermittelt aus den behördlichen Nummern im Dokument
`dekade`	zur Dekadenmeldung an die Behörden vormerken; nur beim Begleitschein und erst wirksam, wenn der Entsorger- oder ein Ergänzungslayer oben liegt
`cancel`	diese Version ist ein Storno; sie wird zugestellt, aber nie an die Behörden gemeldet

Das SDK schickt alle drei Werte ausdrücklich mit und setzt sie standardmäßig auf false, ohne Argumente wird also weder verteilt noch gemeldet. Über gRPC und REST gilt dagegen ein nicht gesetztes distribute oder dekadenmeldung als true. Was beim Vermitteln und Melden genau passiert, wann die Meldung an die Behörde rausgeht und was ZEDAL beim Speichern ablehnt, steht unter Begleitschein je Rolle und Was ZEDAL beim Speichern prüft.

Über REST geht das mit POST /infotech.zedal.core.v1.api.DocumentApi/ImportTransportDocument und den Feldern document, distribute, dekadenmeldung und cancel (Über REST). Setz distribute, dekadenmeldung und cancel immer ausdrücklich.

Übernahmeschein¶

Der Übernahmeschein (Document.Uns, UNSDokument) folgt demselben Arbeitsmodell. Die Unterschiede:

Er hat einen Beförderer (befoerderer) und kein Zwischenlager.
CreateDocument braucht eine ATB-Rolle, ERZ, BEF oder ENT. Ohne sie scheitert der Aufruf mit CANCELLED, auch mit VALIDATION_NONE.
AddLayer scheitert für jeden Layertyp mit CANCELLED.
Der Begleitschein verweist über uns_nrn auf seine Übernahmescheine, nur mit deren Nummern.

→ Umsetzung mit dem .NET SDK

Über REST¶

Die Pfade folgen dem Schema aus REST / JSON, mit den Headern Authorization und provider_id. Bytes-Felder (docXml, templateXml und das Feld document in der Antwort des Muster-Exports, in der Anfrage von ImportTransportDocument und in der Antwort von ExportCurrentDocument) sind base64-kodiert.

Schritt	Operation	Felder der Anfrage
Muster auflisten	`POST /infotech.zedal.core.v1.api.QueryApi/ListTransportTemplates`	`qpar` (Antwort: `entries`, `total`)
Muster herunterladen	`GET /infotech.zedal.core.v1.api.DocumentTemplateApi/ExportTransportTemplate?templateId.id=<id>`	– (Antwort: `document`)
Aus Muster anlegen	`POST /infotech.zedal.bxa.bmu.v1.api.BmuDocumentApi/CreateDocumentFromTemplate`	`templateXml`
Aus Daten anlegen	`POST …/BmuDocumentApi/CreateDocument`	`document`, `vorlageLayer`, `xmlOptions`
Felder setzen	`POST …/BmuDocumentApi/UpdateDocument`	`docXml`, `document`, `xmlOptions`
Layer anhängen	`POST …/BmuDocumentApi/AddLayer`	`docXml`, `layerType`, `xmlOptions`
Lesen	`POST …/BmuDocumentApi/GetDocument`	`docXml`
Signaturstellen	`POST …/BmuDocumentApi/GetValidSignaturePositions`	`docXml`
An ZEDAL senden	`POST /infotech.zedal.core.v1.api.DocumentApi/ImportTransportDocument`	`document`, `distribute`, `dekadenmeldung`, `cancel` (Antwort: `docId`)
Bestand auflisten	`POST …/QueryApi/ListTransportDocuments`	`qpar` (Antwort: `entries`, `total`)
Eingang auflisten	`POST …/QueryApi/ListInboxDocuments`	`qpar` (Antwort: `entries`, `total`)
Dokument laden	`GET …/DocumentApi/ExportCurrentDocument?docId.id=<id>`	– (Antwort: `document`)

POST /infotech.zedal.bxa.bmu.v1.api.BmuDocumentApi/UpdateDocument HTTP/1.1
Host: openapi.test.zedal.de
Authorization: Bearer <access-token>
provider_id: <id>
Content-Type: application/json

{
  "docXml": "<aktuelles XML, base64>",
  "document": {
    "bgs": {
      "menge": { "value": 12.5, "meta": { "inLayer": true } }
    }
  },
  "xmlOptions": { "validation": "VALIDATION_NONE" }
}

Die Antwort trägt document und das neue docXml. Anfragen akzeptieren bei Enum-Feldern die Zahl oder den Namen, Antworten enthalten den Namen:

Feld	Werte
`validation`	`VALIDATION_FULL` (1), `VALIDATION_MANDATORY` (2), `VALIDATION_TYPES` (3), `VALIDATION_NONE` (4)
`pruefziffer`	`PRUEFZIFFER_VALIDATE` (1), `PRUEFZIFFER_CALCULATE` (2)
`layerType`	`VORLAGE` (1), `ERZEUGER` (2), `BEFOERDERER` (3), `ENTSORGER` (4), `BEHOERDE` (5), `ERGAENZUNG` (6), `ZWISCHENLAGER` (7)
`atbRolle`	`ERZ` (1), `BEF` (2), `ZWL` (3), `ENT` (4), `BEH` (5), `PROV` (6), `BEVERZ` (7), `MAK` (8), `SONST` (9)

0 heißt jeweils „nicht gesetzt“: Standard des Aufrufs (validation), Prüfziffern prüfen, VORLAGE bzw. keine Rolle.

Dokument speichern¶

ImportTransportDocument speichert das gesamte XML aus document in ZEDAL. Die Optionen sind die aus An ZEDAL senden, dekade heißt in REST dekadenmeldung. Alle drei sind Objekte mit value:

POST /infotech.zedal.core.v1.api.DocumentApi/ImportTransportDocument HTTP/1.1
Host: openapi.test.zedal.de
Authorization: Bearer <access-token>
provider_id: <id>
Content-Type: application/json

{
  "document": "<aktuelles XML, base64>",
  "distribute": { "value": false },
  "dekadenmeldung": { "value": false },
  "cancel": { "value": false }
}

Die Antwort trägt die Kennung des Dokuments in docId.id. Setz distribute, dekadenmeldung und cancel immer ausdrücklich: Der Typ unterscheidet „nicht gesetzt“ von false, und ohne Angabe gelten distribute und dekadenmeldung als true. Optional nennt templateUsage.templateId.id das Muster, aus dem das Dokument angelegt wurde.

Auflisten und Laden¶

Die drei Listen nehmen im Feld qpar einen QueryParameter:

Feld	Inhalt
`mask`	Spaltenauswahl als Feldmaske
`filter`	Bedingungen aus `path` (Feldpfad), `op` (Operator) und `operands` (Vergleichswerte)
`sort`	Sortierung aus `path` und `direction`
`pageStart`, `pageSize`	Seitensteuerung

op und direction nehmen den Namen oder die Zahl; ohne Angabe gilt 0, also EQUAL bzw. ASC:

Feld	Werte
`op`	`EQUAL` (0), `NOT_EQUAL` (1), `IS_NULL` (2), `IS_NOT_NULL` (3), `CONTAINS` (4), `BEGINS_WITH` (5), `ENDS_WITH` (6), `LESSER_THAN` (7), `GREATER_THAN` (8), `LESSER_OR_EQUAL_THAN` (9), `GREATER_OR_EQUAL_THAN` (10), `BETWEEN` (11), `IN_LIST` (12)
`direction`	`ASC` (0), `DESC` (1)

Jeder Vergleichswert in operands trägt genau einen Typ: s (Text), nInt32 (Ganzzahl), b (Wahrheitswert), n (Dezimalzahl aus units und nanos), d (Datum), dt (Datum mit Uhrzeit) oder utc (Zeitstempel). Feldpfade stehen in Proto-Schreibweise mit Unterstrichen. Begleitscheine im Bestand findet etwa:

POST /infotech.zedal.core.v1.api.QueryApi/ListTransportDocuments HTTP/1.1
Host: openapi.test.zedal.de
Authorization: Bearer <access-token>
provider_id: <id>
Content-Type: application/json

{
  "qpar": {
    "filter": [
      { "path": "doc.document_type", "op": "EQUAL", "operands": [ { "s": "BGS" } ] }
    ],
    "pageSize": 50
  }
}

doc.document_type ist BGS, RGB oder UNS.

Die Antwort trägt die Zeilen in entries und die Gesamtzahl in total. Welche Feldpfade gelten, bestimmt die jeweilige Liste; gängig ist der Filter auf doc.document_type. Eine Zeile aus Bestand oder Eingang trägt doc mit der Kennung in doc.documentId.id, dazu cancelled (Bestand) bzw. read und removed (Eingang). Eine Muster-Zeile trägt templateId, interneBezeichnung, art, format und anzahl, die Felder aus Aus einem ZEDAL-Muster in JSON-Schreibweise; templateId geht als templateId.id in den Export.

Ein Dokument aus dem Bestand lädt ExportCurrentDocument mit der Kennung aus der Zeile. Die Antwort trägt es in document; bei BMU ist das das XML, das die BmuDocumentApi als docXml erwartet. Ein Dokument aus dem Eingang lädst du mit derselben Operation über die Kennung des Eingangsdokuments. Einen Eingang in den Bestand zu übernehmen geht über REST nicht (Grenzen des REST-Wegs).

Größen¶

REST-Antworten dürfen bis 50 MB groß sein; die Grenze gilt für den Inhalt (XML plus typisierte Sicht) vor der Umwandlung in JSON, nicht für die JSON-Größe. Anfragen an openapi.* dürfen dagegen höchstens rund 28 MB groß sein. Weil in JSON die base64-Kodierung mitzählt und das XML um etwa ein Drittel größer macht, passt in eine REST-Anfrage ein XML bis etwa 21 MB. Die Grenzen gelten für jede Operation, auch für document in der Anfrage von ImportTransportDocument (XML bis etwa 21 MB) und in der Antwort von ExportCurrentDocument (bis 50 MB).