AI translation

This page was translated from German with AI. If in doubt, the German original applies.

Consignment note and acceptance note¶

This guide takes a consignment note (Begleitschein) through its lifecycle: create, fill in, sign, next layer, send to ZEDAL. The REST calls are under Via REST; the C# code is in the SDK section.

Prerequisites: access to ZEDAL (Getting started) and the working model from the overview.

With the .NET SDK

The code for this guide is shown in BmuDocumentHandler.

Creating¶

From a ZEDAL template¶

Templates are stored on the ZEDAL server; client.CoreApi.Query.ListTransportTemplates(…) returns the list. For BMU, these fields of an entry matter:

Field	Meaning
`template_id`	identifier for downloading
`interne_bezeichnung`	company-internal designation
`art`	`N` = consignment note, `S` = acceptance note (Übernahmeschein), `L` = record list (Nachweisliste)
`format`	only `BMU` is BMU XML
`anzahl`	number of notes that may be retrieved from the template

→ Implementation with the .NET SDK

From data¶

→ Implementation with the .NET SDK

VALIDATION_NONE turns off validation, for example for a draft; without options, CreateDocument validates fully, and an incomplete consignment note then fails with CANCELLED. With vorlageLayer: true, the document starts with a template layer (Vorlagelayer); in that case, a role belongs in the options, for example AtbRolle = Rolle.Erz.

Setting fields¶

→ Implementation with the .NET SDK

Only fields with InLayer = true are written. The service ignores a field without this marker, and the call still reports success. The short constructors Sf(…) and Df(…) from ProtoFields do not set the marker.
Fields you do not send remain unchanged.
A non-empty list that you send determines the length of the list in the document.
XmlOptions apply only to this call. Without them, UpdateDocument validates fully.

Formats and units: Field rules → BMU.

Signing¶

Layers cannot be signed via the SignerApi yet

For BMU documents, the SignerApi currently does not place a signature at a specific signature position of a layer. Signatures that complete a layer are not yet possible through it. This step will be added as soon as the SignerApi supports it.

The open signature positions in the current layer are returned by GetValidSignaturePositions.

→ Implementation with the .NET SDK

Each position appears twice in the list, without and with envelope (signature over the entire document).

Signing takes place via the WebSigner (infotech.signer.sign.v1): create a process with the current XML and submit it, show the signing_url to a person who signs there, wait for completion, retrieve the result. The result contains the complete signed XML. SignAsync handles this in one call.

DocumentResults.IsUsable (namespace Zedal.Sdk.Apis.Signer) checks that the document is signed and that the verification result does not reject it; a failed document has no content. How SignAsync waits, how you cancel, and how you separate submitting and retrieving (SubmitAsync, GetSigningProcess, GetResults) is described under Signing with the SDK.

Next layer¶

→ Implementation with the .NET SDK

AddLayer also works on a signed consignment note. Without XmlOptions, AddLayer does not validate the new layer. A supplement layer (Ergänzungslayer) needs the role for which it is created, for example AddLayer(LayerType.Ergaenzung, new XmlOptions { AtbRolle = Rolle.Ent }).

Reading¶

→ Implementation with the .NET SDK

Load calls GetDocument and sets DocXml and Document. Document.Meta also contains layers, signatures, and signature positions. LoadTransportDocumentFromZedal(…) loads a document stored in ZEDAL via an identifier.

Sending to ZEDAL¶

→ Implementation with the .NET SDK

The entire current DocXml with all layers is sent to DocumentApi.ImportTransportDocument. If ZEDAL already has a document with the same transport identifier, a new version is created; otherwise, a new document.

Parameter	Effect
`distribute`	deliver to the other parties (forwarding, Vermittlung), determined from the official numbers in the document
`dekade`	flag for the ten-day report (Dekadenmeldung) to the authorities; only for the consignment note and only effective once the disposer (Entsorger) layer or a supplement layer is on top
`cancel`	this version is a cancellation; it is delivered but never reported to the authorities

The SDK sends all three values explicitly and sets them to false by default, so without arguments nothing is forwarded or reported. Via gRPC and REST, by contrast, an unset distribute or dekadenmeldung counts as true. What exactly happens during forwarding and reporting, when the report goes out to the authority, and what ZEDAL rejects on save is described under Consignment note by role and What ZEDAL checks on save.

Via REST, you do this with POST /infotech.zedal.core.v1.api.DocumentApi/ImportTransportDocument and the fields document, distribute, dekadenmeldung, and cancel (Via REST). Always set distribute, dekadenmeldung, and cancel explicitly.

Acceptance note¶

The acceptance note (Document.Uns, UNSDokument) follows the same working model. The differences:

It has one carrier (befoerderer) and no interim storage facility (Zwischenlager).
CreateDocument needs a waste transport party (ATB) role, ERZ, BEF, or ENT. Without it, the call fails with CANCELLED, even with VALIDATION_NONE.
AddLayer fails with CANCELLED for every layer type.
The consignment note refers to its acceptance notes via uns_nrn, only by their numbers.

→ Implementation with the .NET SDK

Via REST¶

The paths follow the scheme from REST / JSON, with the headers Authorization and provider_id. Bytes fields (docXml, templateXml, and the field document in the response of the template export, in the request of ImportTransportDocument, and in the response of ExportCurrentDocument) are base64-encoded.

Step	Operation	Request fields
List templates	`POST /infotech.zedal.core.v1.api.QueryApi/ListTransportTemplates`	`qpar` (response: `entries`, `total`)
Download template	`GET /infotech.zedal.core.v1.api.DocumentTemplateApi/ExportTransportTemplate?templateId.id=<id>`	– (response: `document`)
Create from template	`POST /infotech.zedal.bxa.bmu.v1.api.BmuDocumentApi/CreateDocumentFromTemplate`	`templateXml`
Create from data	`POST …/BmuDocumentApi/CreateDocument`	`document`, `vorlageLayer`, `xmlOptions`
Set fields	`POST …/BmuDocumentApi/UpdateDocument`	`docXml`, `document`, `xmlOptions`
Append layer	`POST …/BmuDocumentApi/AddLayer`	`docXml`, `layerType`, `xmlOptions`
Read	`POST …/BmuDocumentApi/GetDocument`	`docXml`
Signature positions	`POST …/BmuDocumentApi/GetValidSignaturePositions`	`docXml`
Send to ZEDAL	`POST /infotech.zedal.core.v1.api.DocumentApi/ImportTransportDocument`	`document`, `distribute`, `dekadenmeldung`, `cancel` (response: `docId`)
List document store	`POST …/QueryApi/ListTransportDocuments`	`qpar` (response: `entries`, `total`)
List inbox	`POST …/QueryApi/ListInboxDocuments`	`qpar` (response: `entries`, `total`)
Load document	`GET …/DocumentApi/ExportCurrentDocument?docId.id=<id>`	– (response: `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": "<current XML, base64>",
  "document": {
    "bgs": {
      "menge": { "value": 12.5, "meta": { "inLayer": true } }
    }
  },
  "xmlOptions": { "validation": "VALIDATION_NONE" }
}

The response carries document and the new docXml. For enum fields, requests accept the number or the name; responses contain the name:

Field	Values
`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)

In each case, 0 means “not set”: the call’s default (validation), validate check digits, VORLAGE, and no role, respectively.

Saving the document¶

ImportTransportDocument saves the entire XML from document in ZEDAL. The options are those from Sending to ZEDAL; in REST, dekade is called dekadenmeldung. All three are objects with 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": "<current XML, base64>",
  "distribute": { "value": false },
  "dekadenmeldung": { "value": false },
  "cancel": { "value": false }
}

The response carries the document’s identifier in docId.id. Always set distribute, dekadenmeldung, and cancel explicitly: the type distinguishes “not set” from false, and if omitted, distribute and dekadenmeldung count as true. Optionally, templateUsage.templateId.id names the template from which the document was created.

Listing and loading¶

The three lists take a QueryParameter in the field qpar:

Field	Content
`mask`	column selection as a field mask
`filter`	conditions made up of `path` (field path), `op` (operator), and `operands` (comparison values)
`sort`	sorting by `path` and `direction`
`pageStart`, `pageSize`	paging

op and direction take the name or the number; if omitted, 0 applies, i.e. EQUAL or ASC:

Field	Values
`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)

Each comparison value in operands carries exactly one type: s (text), nInt32 (integer), b (Boolean), n (decimal number from units and nanos), d (date), dt (date with time), or utc (timestamp). Field paths use proto notation with underscores. For example, this finds consignment notes in the document store:

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 is BGS, RGB, or UNS.

The response carries the rows in entries and the total count in total. Which field paths apply is determined by the respective list; ZEDAL Forms 4, for example, filters documents by doc.document_type. A row from the document store or the inbox carries doc with the identifier in doc.documentId.id, plus cancelled (document store) or read and removed (inbox). A template row carries templateId, interneBezeichnung, art, format, and anzahl, the fields from From a ZEDAL template in JSON notation; templateId goes into the export as templateId.id.

ExportCurrentDocument loads a document from the document store using the identifier from the row. The response carries it in document; for BMU, this is the XML that the BmuDocumentApi expects as docXml. ZEDAL Forms 4 loads a document from the inbox with the same operation using the identifier of the inbox document and opens it read-only. Importing an inbox entry into the document store is not possible via REST (Limits of the REST path).

Sizes¶

REST responses may be up to 50 MB; the limit applies to the backend’s Protobuf response (XML plus typed view), not to the JSON size. Requests to the gateway (openapi.*), on the other hand, end at around 28 MB. Because the base64 encoding counts in JSON and makes the XML about a third larger, an XML of up to about 21 MB fits via REST. The limits apply to every operation, including document in the request of ImportTransportDocument (XML up to about 21 MB) and in the response of ExportCurrentDocument (up to 50 MB).