Movement mit dem SDK

Setup und je Stage der Aufruf über den MovementDocumentHandler.

Die fachlichen Hintergründe stehen in der Anleitung Movement (Company-Rolle).

Setup

// Authenticated client with an active session — see Getting started
var client = ZedalClientFactory.Default.CreateClient(
    TargetSystem.Test, "MyIntegrationApp", "1.0.0");

await client.CreateSession(
    userId:   "mysubscriber-myaccount@1:mypassword",
    appToken: new AppToken("<APP_TOKEN_JWT>"));

// NotificationId from the preceding notification phase
string notificationId = "DE0126999901i"; // example

Pro Movement ein Handler. Jede Folge-Stage lädt den aktuellen Stand mit LoadFromZedalByMovementId(movementId) neu, damit zwischenzeitliche Änderungen (z.B. ergänzende Anhänge anderer Parteien) berücksichtigt werden.

Stage 1 — CreateMovementTemplate

MovementDocumentHandler handler = client.DocumentHandler.CreateMovementHandler();

// Determine the next free SequenceNumber for this notification
// (returns 1 if no movement exists yet). Determines the number
// from the transport papers already created — there is no
// server-side reservation path as there is for the NotificationId.
int sequenceNumber = await client.DocumentNumbers.GetNextMovementSequenceNumber(notificationId);

var template = new MovementTemplateType
{
    // Template.NotificationId = notificationId
    // Template.SequenceNumber = sequenceNumber
    // planned departure date, planned quantity, packaging,
    // further required fields under Regulation (EU) 2024/1157 …
};

await handler.CreateMovementTemplate(template);
await handler.SaveToZedal();
await handler.SendToDiwass();

string movementId = handler.DiwassNotificationId;
// MovementDocumentHandler exposes the movement ID via the inherited property
// DiwassNotificationId (format: <NotificationId>.<SequenceNumber>MOV,
// e.g. DE0126999901i.000001MOV).

Stage 2 — SetCarrierTransport

Sobald der physische Transport beginnt, erfasst der Beförderer die Transport-Daten:

var handler = client.DocumentHandler.CreateMovementHandler();
await handler.LoadFromZedalByMovementId(movementId);

await handler.SetCarrierTransport(new CarrierTransportDocumentType
{
    // vehicle identification, actual departure date,
    // confirmation of takeover …
});
await handler.SaveToZedal();
await handler.SendToDiwass();

Stage 3 — SetConsigneeReception

Der Empfänger bestätigt den Wareneingang:

var handler = client.DocumentHandler.CreateMovementHandler();
await handler.LoadFromZedalByMovementId(movementId);

await handler.SetConsigneeReception(new ConsigneeReceptionDocumentType
{
    // date of receipt, quantity actually accepted,
    // quantity difference with justification (if necessary) …
});
await handler.SaveToZedal();
await handler.SendToDiwass();

Stage 4 — SetFacilityReception

var handler = client.DocumentHandler.CreateMovementHandler();
await handler.LoadFromZedalByMovementId(movementId);

await handler.SetFacilityReception(new FacilityReceptionDocumentType
{
    // date of acceptance at the facility, accepted quantity,
    // planned R/D code according to the annex of the regulation …
});
await handler.SaveToZedal();
await handler.SendToDiwass();

Stage 5 — SetFacilityCompletion

Die Anlage schließt die Behandlung ab. Stage 5 markiert das Ende des regulären Lebenszyklus:

var handler = client.DocumentHandler.CreateMovementHandler();
await handler.LoadFromZedalByMovementId(movementId);

await handler.SetFacilityCompletion(new FacilityCompletionDocumentType
{
    // completion date of the treatment, R/D code actually applied,
    // quantity actually treated …
});
await handler.SaveToZedal();
await handler.SendToDiwass();

Validierung und Fehlerbehandlung

Wie bei der Notification validiert der Movement-Handler vor dem Push:

await handler.SendToDiwass();
// Throws an exception on server-side rejection.
// Validation details (e.g. invalid R/D codes, missing required fields)
// are in handler.ValidationErrors (HasValidationErrors as a convenience flag).
//
// Optionally wait for the transfer acknowledgment:
// Size the time budget to the payload — the client default of 30 s is not enough here.
// A push with an attachment takes more than 90 s; in a multi-stage movement chain,
// a stage can take 3 to 5 minutes. See Lifecycle -> Sending procedure.
await handler.WaitForDiwassTransfer(
    timeout:      TimeSpan.FromMinutes(6),
    pollInterval: TimeSpan.FromSeconds(5));
// Throws DiwassTransferFailedException on rejection by DiWaSS,
// TimeoutException on timeout.

Häufige Fehlerquellen:

• Stage außer der Reihe: SetFacilityReception ohne vorherige SetConsigneeReception wird abgewiesen — außer Consignee und Facility sind in der Notification derselbe Operator; dann entfällt Stage 3 und Stage 4 folgt direkt auf Stage 2.
• R-/D-Code unbekannt: der angegebene Behandlungs-Code muss zur in der Notification genehmigten Liste gehören.
• Mengenbilanz unschlüssig: Differenzen zwischen geplanter und tatsächlicher Menge erfordern in Stage 3 und 5 eine QuantityBalance-Begründung.