Speicherbereiche: Inbox, Nachweis-Bereich, Versandpapier-Bereich¶

Jeder ZEDAL-Account hat drei klar getrennte Speicherbereiche, in denen Dokumente liegen können. Wer das Modell einmal kennt, versteht fast alle Core-Aufrufe sofort — ohne dieses Vokabular wirken Methodennamen wie ImportTransportDocument, ImportDocumentToFileArea oder RemoveDocumentsFromInbox willkürlich.

Auf einen Blick¶

Bereich	Grundidee	Strukturmodell	Typische Inhalte
Inbox (Posteingang)	Eingehende Dokumente, noch nicht verarbeitet	flache Liste pro Account	Movements von Geschäftspartnern, Mitteilungen, Neueingänge aller Art
Nachweis-Bereich (File Area)	Akten-basierte Langzeit-Ablage für mehrteilige Vorgänge	hierarchisch: Akte (`File`) → Dokumente	DiWaSS-Notifizierungen, Genehmigungen, Mehr-Dokument-Vorgänge
Versandpapier-Bereich (Transport Paper Area)	Verteil- und Quittierungs-Schiene für Einzel-Dokumente entlang einer Beförderungskette	flache Liste mit Distribution-Status	Movements, Annex VII, Begleitscheine, einzelne Transportpapiere

flowchart LR
    EXT[Externe Sender<br/>andere Subscriber, ZKS, DiWaSS]
    INBOX[(Inbox)]
    FILE[(Nachweis-Bereich<br/>Akten-basiert)]
    TRANS[(Versandpapier-<br/>Bereich)]
    APP[Eigene Anwendung]

    EXT -->|"Versand / Verteilung"| INBOX
    INBOX -->|"Import zu Akte"| FILE
    INBOX -->|"Import als Transport"| TRANS
    APP -->|"Akte anlegen / Dokument importieren"| FILE
    APP -->|"Transport-Dokument importieren"| TRANS
    FILE -.->|"Submission / Grant"| EXT
    TRANS -.->|"Verteilung an Beteiligte"| EXT

Die drei Bereiche sind nicht hierarchisch, sondern parallel — ein Dokument kann in der Inbox eines Accounts liegen und parallel als Importkopie im Nachweis-Bereich oder Versandpapier-Bereich desselben oder eines anderen Accounts.

Inbox¶

Die Inbox ist der Posteingang eines Accounts: eine flache Liste von Dokumenten, die für diesen Account eingegangen sind — ähnlich einem E-Mail-Postfach, aber mit ZEDAL-Dokumenten als Inhalten.

Wann landet etwas in der Inbox:

ein anderer Beteiligter schickt ein Dokument ausdrücklich an den Account (SendDocument legt eine Kopie in den Posteingang des Empfängers);
ein Versandpapier kommt über die ZKS-Abfall von einem Beteiligten, der bei einem anderen eANV-Anbieter ist;
eine Verteilung (Distribution) trifft auf einen Account, der unter derselben fachlichen Nummer bereits ein anderes Versandpapier führt; die Zustellung in die Inbox ist dann nicht garantiert;
eingehende DiWaSS-Dokumentversionen erscheinen als Inbox-Eintrag, bevor sie importiert werden.

Zwei Statusflags pro Eintrag (read und removed, sichtbar in der Listenantwort von ListInboxDocuments):

Flag	Bedeutung	Wer setzt
`read`	Eintrag wurde gesichtet	`SetInboxDocumentsRead`
`removed`	Eintrag wurde aus der Inbox-Sicht entfernt (logisch, nicht physisch gelöscht)	`RemoveDocumentsFromInbox`

ListInbox ohne Bedingungsparameter listet alle ungelesenen Dokumente ohne zeitliche Einschränkung. Wer gezielt filtern will, gibt einen Bedingungsparameter mit; der Inbox-Importer des SDK arbeitet auf removed = false und optional auf document_type.

Inbox-Filter: Im ZEDAL-Portal konfigurierte automatische Filterregeln lassen sich anwendungsseitig über ApplyInboxFilter auslösen — der Aufruf führt die dort konfigurierten Regeln aus.

Der Import ist der Zustellweg, nicht das Aufräumen

Inbox-Einträge sind keine eigenen Dokumente, sondern Verweise auf eingehende Dokumente. Das eigentliche Dokument gelangt erst durch einen Import in den Nachweis- oder Versandpapier-Bereich. Wer nicht importiert, sieht eingehende Dokumentversionen nie im eigenen Bestand — auch nicht durch wiederholtes Laden.

Der Inbox-Eintrag bleibt beim Import bestehen; erst RemoveDocumentsFromInbox entfernt ihn aus der Sicht. Der vollständige Abgleichzyklus steht unter Aufrufe und Synchronisation.

Nachweis-Bereich (File Area)¶

Der Nachweis-Bereich ist der Aktenschrank eines Accounts. Sein Strukturmodell ist hierarchisch:

eine Akte (File) ist ein logischer Ordner mit eindeutiger FileId;
in einer Akte liegen ein oder mehrere Dokumente, jedes mit eigener DocumentId;
jedes Dokument kann mehrere Versionen haben — Updates erzeugen eine neue Version, nicht ein neues Dokument.

Wann nutzt man eine Akte:

mehrteilige Vorgänge: alles, was über mehrere Korrespondenzschritte und Wochen oder Monate läuft. Eine DiWaSS-Notifizierung mit Acknowledgements, Nachforderungen, Entscheidungen und Anhängen ist das Paradebeispiel.
dauerhafte Ablage: Genehmigungen, Zertifikate, Analysenberichte — alles, was zu Nachweiszwecken aufbewahrt werden muss.
gemeinschaftliche Bearbeitung: Übergabe an einen Geschäftspartner zur Bearbeitung.

Submission-Lebenszyklus¶

Akten haben einen eigenen Bearbeitungs-Lebenszyklus. Wichtig dabei: Nicht jeder Schritt wird von derselben Seite ausgelöst. Wer das verwechselt, baut Zustandsübergänge ein, die der Server ablehnt.

Operation	Wer ruft	Wirkung
`OpenSubmission`	einreichende Seite	Übergibt die Akte an eine interne oder externe Partei zur Bearbeitung. Ohne Grant-Optionen werden alle öffentlichen Dokumente mit Standard-Berechtigungen übergeben
`HoldSubmission`	einreichende Seite	Die Einreichung kann für eine bestimmte Zeit nicht zurückgezogen werden
`CompleteSubmission`	empfangende Seite	Setzt die Einreichung auf „bearbeitet”. Der Empfänger erhält die Berechtigungen der Einreichung dauerhaft
`RejectSubmission`	empfangende Seite	Weist die Einreichung zurück. Die durch sie gewonnenen temporären Berechtigungen entfallen
`CancelSubmission`	einreichende Seite	Zieht eine offene Einreichung zurück; sie ist danach abgeschlossen, temporäre Berechtigungen entfallen
`DiscardFinishedSubmission`	—	Verwirft eine bereits abgeschlossene Einreichung
`SetLocalSubmission`	—	Setzt die Akte auf lokale Bearbeitung

Ob ein Aufruf durchgeht, hängt in jedem Fall vom aktuellen Submission-Zustand ab — nicht nur von der Berechtigung. Den Bestand liest man über ListNewSubmissions, ListAllSubmissions, ListCompletedSubmissions und ListRejectedSubmissions.

Zugriff¶

Der Aktenersteller hat Vollzugriff. Andere Parteien erhalten Zugriff über GrantAccessToFile und verlieren ihn wieder über RevokeAccessFromFile. Der Grant kennt eine optionale Ablauffrist (expires_at) und granulare Berechtigungen:

Berechtigung	Erlaubt dem Empfänger
`edit`	das Objekt zu bearbeiten
`submit`	das Objekt einzureichen
`grant`	selbst einen Grant für das Objekt zu öffnen
`include_transport_documents`	auch die zugehörigen Transportpapiere zu sehen

Ergänzend steuert ChangeDocumentPrivacyLevel den Privacy-Level je Dokument.

Importe¶

Operation	Verhalten
`ImportDocumentToFileArea(bytes, minPrivacyLevel)`	Der Server sucht selbst eine passende Akte und ein passendes Dokument. Treffer: neue Version dort. Kein Treffer: neue Akte mit neuem Dokument
`ImportDocumentToFile(bytes, minPrivacyLevel, fileId)`	Wie oben, aber in einer bestimmten Akte
`ImportDocumentToFileAreaFromInbox(inboxDocId, minPrivacyLevel)`	Variante über die Inbox; Ziel-Akte bestimmt der Server
`ImportDocumentToFileFromInbox(inboxDocId, fileId, minPrivacyLevel)`	Variante über die Inbox in eine bestimmte Akte
`ImportNewDocumentToFileFromInbox(inboxDocId, fileId, minPrivacyLevel)`	Erzwingt ein neues Dokument in der Akte statt einer neuen Version
`ImportToDocumentInFileFromInbox(inboxDocId, targetDocId)`	Hängt an ein bestimmtes bestehendes Dokument an
`ImportToDocument(bytes, documentId)`	Neue Version an ein bestimmtes Dokument — funktioniert in jedem schreibbaren Bereich

Die Import-Operationen sind nur über gRPC erreichbar

Keine der hier genannten Operationen trägt eine HTTP-Annotation, sie erscheinen daher nicht in der OpenAPI-Spezifikation. Von den Import…-Operationen der DocumentApi hat nur ImportTransportDocument eine REST-Route. Über REST/JSON kannst du die Inbox lesen und aufräumen, aber nicht übernehmen. Siehe Plattform-Architektur → Services.

Versandpapier-Bereich (Transport Paper Area)¶

Der Versandpapier-Bereich ist die Verteil- und Quittierungs-Schiene für Dokumente, die entlang einer Beförderungskette zugestellt werden müssen. Sein Strukturmodell ist eine flache Liste — keine Akten, keine Hierarchie. Jedes Transport-Dokument steht für sich.

Wann nutzt man den Versandpapier-Bereich:

Movements: jede DiWaSS-Verbringung ist ein eigenständiges Transport-Dokument.
Annex-VII-Dokumente und nationale Begleitscheine, Lieferscheine, Transport-Quittungen.
Distribution an Beteiligte: Das System erkennt aus dem Dokument, wer beteiligt ist, und stellt jedem eine Kopie in seinen Versandpapier-Bereich: bei DiWaSS-Dokumenten die Operatoren (Notifier, Carrier, Consignee, Facility), beim Begleitschein die behördlichen Nummern von Erzeuger, Beförderern, Zwischenlager und Entsorger. Beteiligte bei anderen eANV-Anbietern erreicht ein Begleitschein über die ZKS-Abfall.

Peek-and-Acknowledge¶

Das charakteristische Verhalten dieses Bereichs ist eine Warteschlange, die erst nach ausdrücklicher Quittung weiterrückt:

PeekNextTransportDocument liefert das nächste noch nicht quittierte Transport-Dokument als (DocumentId, LogId). Der Aufruf entfernt nichts aus der Liste.
Die Anwendung lädt und verarbeitet das Dokument.
SetTransportDocumentReceived mit den Werten aus Schritt 1 bestätigt den Empfang. Erst danach liefert der nächste Peek den folgenden Eintrag.

Damit kann kein Transport-Dokument unbemerkt verloren gehen: Bricht die Verarbeitung ab, bleibt das System am selben Eintrag stehen. Der Preis dafür ist, dass ein nicht quittierter Eintrag die Warteschlange blockiert — ein Peek ohne folgendes SetTransportDocumentReceived liefert dauerhaft dasselbe Dokument.

Zwei verwandte Paare mit anderem Zweck:

Paar	Wofür
`PeekNextFileAreaDocument` / `SetFileAreaDocumentReceived`	Dieselbe Schleife für Akten-Dokumente, die per Distribution zugestellt werden
`PeekNextAcknowledgableTransportDocument` / `AcknowledgeTransportDocument`	Fachliche Quittung an den Absender zurück; der Empfänger kann Status-Info und einen Text mitgeben. Nicht zu verwechseln mit der Empfangsbestätigung oben

Importe¶

Operation	Verhalten
`ImportTransportDocument(bytes, cancel, dekade, distribute, …)`	Der Server gleicht die fachlichen Transport-Kennungen gegen den Bestand ab. Treffer: neue Version. Kein Treffer: neuer Eintrag
`ImportTransportDocumentFromInbox(inboxDocId, dekade, distribute)`	Variante über die Inbox. Die Kennzeichen wertet der Server hier nicht aus: Er stellt das Dokument den Beteiligten bei ZEDAL zu und meldet es nicht an die Behörden

Über REST ist nur ImportTransportDocument erreichbar (BMU: Über REST zeigt den Aufruf), die Variante über die Inbox gibt es nur über gRPC.

Zwei Parameter mit Nebenwirkung:

distribute — verteilt das Dokument automatisch an alle im Dokument enthaltenen Beteiligten. Ohne Angabe gilt true; das .NET SDK setzt ohne Angabe false.
cancel — importiert das Dokument mit gesetztem Storno-Zustand.

SDK: welcher Handler wohin speichert¶

SaveToZedal() wählt den Zielbereich anhand des Handler-Typs. Das ist nicht durchgehend intuitiv — die Behördensicht auf ein Movement landet im Nachweis-Bereich, die Unternehmenssicht im Versandpapier-Bereich:

Handler	Zielbereich von `SaveToZedal()`
`NotificationDocumentHandler`	Nachweis-Bereich
`AuthorityNotificationDocumentHandler`	Nachweis-Bereich
`AuthorityMovementDocumentHandler`	Nachweis-Bereich
`MovementDocumentHandler`	Versandpapier-Bereich
`Annex7DocumentHandler`	Versandpapier-Bereich
`BmuDocumentHandler`	Versandpapier-Bereich

Liegt bereits eine ZedalDocumentId vor, aktualisiert SaveToZedal() das bestehende Dokument an seinem Ort (ImportToDocument) und wechselt den Bereich nicht. Beim Ziel Nachweis-Bereich kannst du über den Parameter targetFile eine bestimmte Akte vorgeben; beim Ziel Versandpapier-Bereich wird er ignoriert, weil es dort keine Akten gibt.

Typischer Workflow durch alle drei Bereiche¶

Ein DiWaSS-Movement berührt alle drei Bereiche eines Empfänger-Accounts:

Das Movement wird zugestellt — es entsteht ein Inbox-Eintrag beim Carrier-Account.
Die Carrier-Anwendung listet die Inbox (ListInbox) und findet den neuen Eintrag.
Der Carrier importiert: ImportTransportDocumentFromInbox legt das Movement im Versandpapier-Bereich ab.
Die Anwendung verarbeitet es (Carrier-Transport-Stage setzen, an DiWaSS senden).
Führt der Carrier zusätzlich eine eigene Akte zum Vorgang, wird die Notifizierung über ImportDocumentToFileAreaFromInbox in den Nachweis-Bereich übernommen.
Nach abgeschlossener Verarbeitung entfernt RemoveDocumentsFromInbox den Inbox-Eintrag aus der laufenden Sicht.

Notifizierungen nehmen denselben Weg, landen aber im Nachweis-Bereich, weil sie konzeptionell ein mehrteiliger Aktenvorgang sind.

Wichtige Eigenschaften, an die man sich gewöhnen sollte¶

Importe sind Kopien, nicht Bewegungen. Ein Import aus der Inbox lässt den Inbox-Eintrag unverändert. Erst RemoveDocumentsFromInbox bereinigt die Sicht.
Server-Match ist die Regel. Importe in Nachweis- und Versandpapier-Bereich gleichen fachliche Kennungen gegen den Bestand ab, bevor neue Einträge entstehen. Dasselbe Dokument zweimal importieren erzeugt zwei Versionen, kein Duplikat. Baue keine clientseitige Zuordnungslogik daneben.
Zwei Wege, ein Dokument weiterzugeben. SendDocument legt eine Kopie in den Posteingang des Empfängers. DeliverDocument erteilt einem ZEDAL-Subscriber stattdessen Berechtigungen auf dem Dokument und vermeidet Kopien, wo es geht; für ZKS-Parteien fällt es auf den Versand zurück.
Distribution ist eine eigene Schiene. Wer eine Kopie an alle Beteiligten verteilen will, nutzt distribute beim Import. Empfänger bei ZEDAL sehen das Dokument dann im Versandpapier- oder Nachweis-Bereich, nicht in der Inbox. Ausnahmen sind Begleitscheine, die über die ZKS-Abfall von anderen eANV-Anbietern kommen, und Empfänger, die unter derselben fachlichen Nummer schon ein anderes Dokument führen: Sie landen in der Inbox; im zweiten Fall ist die Zustellung in die Inbox nicht garantiert.
Subscriber-Isolation. Jeder Account sieht nur die Dokumente in seinen eigenen drei Bereichen. Eine geteilte Aktensicht entsteht erst durch GrantAccessToFile, eine geteilte Transport-Distribution durch die Operator-Beteiligung im Dokument selbst.

Wo es weitergeht¶

Erste Schritte — erstes Inbox-Listing als Smoke-Test
Aufrufe und Synchronisation — wie Inbox-Import und Ereignisabgleich zusammenspielen
.NET SDK → DocumentHandler — die SDK-Abstraktion über die Bereiche
DiWaSS-Lebenszyklus — wie Notifizierungen und Movements durch die Bereiche wandern
Glossar — Begriffe und Abkürzungen