Skip to content

AI translation

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

Storage areas: inbox, file area, transport paper area

Every ZEDAL account has three clearly separated storage areas in which documents can be stored. Once you know the model, you will understand almost all core calls straight away — without this vocabulary, method names such as ImportTransportDocument, ImportDocumentToFileArea or RemoveDocumentsFromInbox seem arbitrary.

At a glance

Area Basic idea Structural model Typical contents
Inbox (Posteingang) Incoming documents, not yet processed flat list per account Movements from business partners, messages, new arrivals of all kinds
File area (Nachweis-Bereich) File-based long-term storage for multi-part cases hierarchical: file (File) → documents DIWASS notifications, permits, multi-document cases
Transport paper area (Versandpapier-Bereich) Distribution and acknowledgment channel for individual documents along a transport chain flat list with distribution status Movements, Annex VII, consignment notes (Begleitscheine), individual transport papers 
flowchart LR
    EXT[External senders<br/>other subscribers, ZKS, DIWASS]
    INBOX[(Inbox)]
    FILE[(File area<br/>file-based)]
    TRANS[(Transport paper<br/>area)]
    APP[Your own application]

    EXT -->|"Sending / distribution"| INBOX
    INBOX -->|"Import to file"| FILE
    INBOX -->|"Import as transport"| TRANS
    APP -->|"Create file / import document"| FILE
    APP -->|"Import transport document"| TRANS
    FILE -.->|"Submission / grant"| EXT
    TRANS -.->|"Distribution to parties"| EXT

The three areas are not hierarchical but parallel — a document can be in the inbox of one account and at the same time exist as an imported copy in the file area or transport paper area of the same or another account.

Inbox

The inbox is an account’s incoming mail: a flat list of documents that have arrived for this account — similar to an email mailbox, but with ZEDAL documents as its contents.

When something ends up in the inbox:

  • another party explicitly sends a document to the account (SendDocument places a copy in the recipient’s inbox);
  • a transport paper arrives via the ZKS-Abfall from a party that uses another eANV provider;
  • a distribution reaches an account that already holds another transport paper under the same business number; depending on the state, ZEDAL then delivers to the inbox or not at all;
  • incoming DIWASS document versions appear as an inbox entry before they are imported.

Two status flags per entry (read and removed, visible in the list response of ListInboxDocuments):

Flag Meaning Set by
read Entry has been viewed SetInboxDocumentsRead
removed Entry has been removed from the inbox view (logically, not physically deleted) RemoveDocumentsFromInbox

ListInbox without condition parameters lists all unread documents without any time restriction. If you want to filter specifically, pass a condition parameter; the SDK’s inbox importer works on removed = false and optionally on document_type.

Inbox filters: automatic filter rules configured in the ZEDAL portal can be triggered from the application via ApplyInboxFilter — the call runs the rules configured there.

The import is the delivery path, not cleanup

Inbox entries are not documents of their own, but references to incoming documents. The actual document only reaches the file area or transport paper area through an import. If you do not import, you will never see incoming document versions in your own store — not even by reloading repeatedly.

The inbox entry remains in place on import; only RemoveDocumentsFromInbox removes it from the view. The complete synchronization cycle is described under Calls and synchronization.

File area (Nachweis-Bereich)

The file area is an account’s filing cabinet. Its structural model is hierarchical:

  • a file (File) is a logical folder with a unique FileId;
  • a file contains one or more documents, each with its own DocumentId;
  • each document can have several versions — updates create a new version, not a new document.

When to use a file:

  • multi-part cases: anything that runs over several correspondence steps and weeks or months. A DIWASS notification with acknowledgments, requests for additional information, decisions and attachments is the prime example.
  • permanent storage: permits, certificates, analysis reports — anything that has to be retained for record-keeping purposes.
  • collaborative processing: handing over to a business partner for processing.

Submission lifecycle

Files have their own processing lifecycle. Important: not every step is triggered by the same side. If you mix this up, you will build in state transitions that the server rejects.

Operation Who calls Effect
OpenSubmission submitting side Hands the file over to an internal or external party for processing. Without grant options, all public documents are handed over with default permissions
HoldSubmission submitting side The submission cannot be withdrawn for a certain period of time
CompleteSubmission receiving side Sets the submission to “processed”. The recipient receives the permissions of the submission permanently
RejectSubmission receiving side Rejects the submission. The temporary permissions gained through it lapse
CancelSubmission submitting side Withdraws an open submission; it is then closed, and temporary permissions lapse
DiscardFinishedSubmission — Discards a submission that has already been closed
SetLocalSubmission — Sets the file to local processing

Whether a call goes through always depends on the current submission state — not just on the permission. You read the current submissions via ListNewSubmissions, ListAllSubmissions, ListCompletedSubmissions and ListRejectedSubmissions.

Access

The creator of the file has full access. Other parties are given access via GrantAccessToFile and lose it again via RevokeAccessFromFile. The grant supports an optional expiration (expires_at) and granular permissions:

Permission Allows the recipient
edit to edit the object
submit to submit the object
grant to open a grant for the object themselves
include_transport_documents to also see the associated transport papers

In addition, ChangeDocumentPrivacyLevel controls the privacy level per document.

Imports

Operation Behavior
ImportDocumentToFileArea(bytes, minPrivacyLevel) The server itself searches for a matching file and a matching document. Match: new version there. No match: new file with a new document
ImportDocumentToFile(bytes, minPrivacyLevel, fileId) As above, but in a specific file
ImportDocumentToFileAreaFromInbox(inboxDocId, minPrivacyLevel) Variant via the inbox; the server determines the target file
ImportDocumentToFileFromInbox(inboxDocId, fileId, minPrivacyLevel) Variant via the inbox into a specific file
ImportNewDocumentToFileFromInbox(inboxDocId, fileId, minPrivacyLevel) Forces a new document in the file instead of a new version
ImportToDocumentInFileFromInbox(inboxDocId, targetDocId) Appends to a specific existing document
ImportToDocument(bytes, documentId) New version on a specific document — works in any writable area

The import operations can only be reached via gRPC

None of the operations listed here carries an HTTP annotation, so they do not appear in the OpenAPI specification. Of the Import… operations of the DocumentApi, only ImportTransportDocument has a REST route. Via REST/JSON you can read and clean up the inbox, but not take entries over. See Platform architecture → Services.

Transport paper area (Versandpapier-Bereich)

The transport paper area is the distribution and acknowledgment channel for documents that have to be delivered along a transport chain. Its structural model is a flat list — no files, no hierarchy. Each transport document stands on its own.

When to use the transport paper area:

  • Movements: every DIWASS shipment is a separate transport document.
  • Annex VII documents and national consignment notes, delivery notes, transport receipts.
  • Distribution to parties: the system recognizes from the document who is involved and places a copy in each one’s transport paper area: for DIWASS documents the operators (notifier, carrier, consignee, facility), for the consignment note the official numbers of waste producer, carriers, interim storage facility and disposer. A consignment note reaches parties at other eANV providers via the ZKS-Abfall.

Peek-and-acknowledge

The characteristic behavior of this area is a queue that only moves on after an explicit acknowledgment:

  1. PeekNextTransportDocument returns the next transport document that has not yet been acknowledged as (DocumentId, LogId). The call does not remove anything from the list.
  2. The application loads and processes the document.
  3. SetTransportDocumentReceived with the values from step 1 confirms receipt. Only then does the next peek return the following entry.

This means that no transport document can get lost unnoticed: if processing aborts, the system stays at the same entry. The price for this is that an unacknowledged entry blocks the queue — a peek without a subsequent SetTransportDocumentReceived returns the same document indefinitely.

Two related pairs with a different purpose:

Pair Purpose
PeekNextFileAreaDocument / SetFileAreaDocumentReceived The same loop for file documents delivered via distribution
PeekNextAcknowledgableTransportDocument / AcknowledgeTransportDocument Business acknowledgment back to the sender; the recipient can include status information and a text. Not to be confused with the confirmation of receipt above

Imports

Operation Behavior
ImportTransportDocument(bytes, cancel, dekade, distribute, …) The server matches the business transport identifiers against the store. Match: new version. No match: new entry
ImportTransportDocumentFromInbox(inboxDocId, dekade, distribute) Variant via the inbox. The server does not evaluate the flags here: it delivers the document to the parties at ZEDAL and does not report it to the authorities

Only ImportTransportDocument can be reached via REST (BMU: Via REST shows the call); the variant via the inbox is only available via gRPC.

Two parameters with side effects:

  • distribute — automatically distributes the document to all parties contained in the document. If not specified, true applies; the .NET SDK sets false if not specified.
  • cancel — imports the document with the withdrawal state set.

SDK: which handler saves where

SaveToZedal() selects the target area based on the handler type. This is not intuitive throughout — the authority view of a movement ends up in the file area, the company view in the transport paper area:

Handler Target area of SaveToZedal()
NotificationDocumentHandler File area
AuthorityNotificationDocumentHandler File area
AuthorityMovementDocumentHandler File area
MovementDocumentHandler Transport paper area
Annex7DocumentHandler Transport paper area
BmuDocumentHandler Transport paper area

If a ZedalDocumentId already exists, SaveToZedal() updates the existing document in its location (ImportToDocument) and does not change the area. If the target is the file area, you can specify a particular file via the targetFile parameter; if the target is the transport paper area, it is ignored, because there are no files there.

Typical workflow through all three areas

A DIWASS movement touches all three areas of a recipient account:

  1. The movement is delivered — an inbox entry is created in the carrier account.
  2. The carrier application lists the inbox (ListInbox) and finds the new entry.
  3. The carrier imports: ImportTransportDocumentFromInbox stores the movement in the transport paper area.
  4. The application processes it (sets the carrier transport stage, sends to DIWASS).
  5. If the carrier also keeps its own file on the case, the notification is taken over into the file area via ImportDocumentToFileAreaFromInbox.
  6. Once processing is complete, RemoveDocumentsFromInbox removes the inbox entry from the current view.

Notifications take the same route, but end up in the file area, because conceptually they are a multi-part file case.

Important properties to get used to

  • Imports are copies, not moves. An import from the inbox leaves the inbox entry unchanged. Only RemoveDocumentsFromInbox cleans up the view.
  • Server-side matching is the rule. Imports into the file area and transport paper area match business identifiers against the store before new entries are created. Importing the same document twice creates two versions, not a duplicate. Do not build any client-side matching logic alongside it.
  • Two ways to pass on a document. SendDocument places a copy in the recipient’s inbox. DeliverDocument instead grants a ZEDAL subscriber permissions on the document and avoids copies where possible; for ZKS parties it falls back to sending.
  • Distribution is a separate channel. If you want to distribute a copy to all parties, use distribute on import. Recipients at ZEDAL then see the document in the transport paper area or file area, not in the inbox. Exceptions are consignment notes that arrive via the ZKS-Abfall from other eANV providers, and recipients that already hold another document under the same business number: they end up in the inbox, in the second case possibly not at all.
  • Subscriber isolation. Each account only sees the documents in its own three areas. A shared file view only comes about through GrantAccessToFile, a shared transport distribution through the operator’s involvement in the document itself.

Where to go next