Skip to content

AI translation

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

Competent authority side (Authority)

This page describes the operations that a competent authority (CA) triggers on a notification or a movement: acknowledgment of receipt, request for additional information, precondition signals, decision, reply to a request for change, take-back order.

For most readers this is not a use case of its own

If you connect a company system, you build the company side — Notification (Company) and Movement (Company). The authority role requires an account that has a CA assigned to it; a company account cannot take on this role.

Still, this page is required reading when you build the company side: almost every state change of your notification is triggered by the authority side. You need to know which operations come from there, in which order they arrive, which of them are irreversible and which of them take away your write access to your own document. The section What reaches you summarizes exactly that.

Prerequisites for the authority role:

With the .NET SDK

The code for this guide is shown in Authority side with the SDK.

The authority API surface at a glance

The authority operations live on a separate API (AuthorityDocumentApi), apart from the company API. It has nine operations:

Operation Level Payload SDK method
SubmitAcknowledgement Notification AcknowledgementDocumentType AuthorityNotificationDocumentHandler.SubmitAcknowledgement
SetRequestInformation Notification RequestInformationDocumentType AuthorityNotificationDocumentHandler.SetRequestInformation
SetDecision Notification DecisionDocumentType AuthorityNotificationDocumentHandler.SetDecision
ReplyToRequestForChangeAfterConsent Notification ReplyToRequestForChangeAfterConsentDocumentType AuthorityNotificationDocumentHandler.ReplyToRequestForChangeAfterConsent
SubmitNotificationSignal Notification NotificationSignalDocumentType AuthorityNotificationDocumentHandler.SubmitNotificationSignal
SetMovementTakeBack Movement MovementTakeBackDocumentType AuthorityMovementDocumentHandler.SetMovementTakeBack
SubmitMovementSignal Movement MovementSignalDocumentType AuthorityMovementDocumentHandler.SubmitMovementSignal
SetByIntent Notification, Annex VII Retrieval document + DiwassIntents client.BxaApi.AuthorityDocumentApi.SetByIntent
GetDocument all — not via the handlers; reading goes through Refresh()

SetByIntent is a generic alternative for form-based user interfaces: instead of a typed operation, you send the complete retrieval document plus the intent, and the server extracts the matching section. Functionally equivalent to the typed operations. Movement documents are explicitly excluded — for them, only the typed path works.

Notification: the operations in detail

Acknowledgment of receipt (SubmitAcknowledgement)

The acknowledgment of receipt starts the time limit for the decision. For authorities that work directly in the EU central system, DIWASS generates it itself; via the API it is needed only when an authority acts on behalf of another authority.
Precondition Notification in status Submitted; no acknowledgment exists yet for the authority concerned
Required fields UserCompetentAuthorityDomainId, NotificationId, Acknowledgement (with ReceiptDate and SentDate)
Effect Receipt acknowledged. Not consent — the notifier may not ship yet

Request for additional information (SetRequestInformation)

Only authorities can request additional information; only the notifier can reply. The window of an open request for additional information is the only opportunity to change anything in a submitted notification — see The change window.
Precondition Notification in status Submitted; the previous request for additional information from the same authority has been answered
Limit At most three requests for additional information per authority and notification
Updatable Yes, any number of times — as long as the request is unanswered and comes from the same authority
Required fields Statement (with NotificationId, text and signature). AdditionalDaysToReply is optional
Effect Time limit for the decision suspended; the notification becomes editable again for the notifier

After ProperlyCarriedOut, the authority of dispatch may no longer request additional information

The order is a one-way street: as soon as the competent authority of dispatch has set its precondition signal, its right to request additional information is used up. The authorities of destination and transit can still request additional information afterward.

Precondition signals: ProperlyCarriedOut and ProperlyCompleted

Before the decision, the authorities establish that the notification is in order from their point of view. Both signals go through the same method SubmitNotificationSignal, distinguished solely by Statement.Signal.TypeCode.

The order is strict and has consequences for the company side:

  1. After submission, only the authority of dispatch can act on the document. All other authorities concerned can see it but cannot set anything.
  2. The authority of dispatch requests additional information if needed and then sets ProperlyCarriedOut once.
  3. Only then can the authorities of destination and transit request additional information and each set ProperlyCompleted once.
  4. When the last of them has set ProperlyCompleted, the status changes — and only then are decisions permitted.
Signal Who How often Precondition
ProperlyCarriedOut Authority of dispatch (WSRDISP) exactly once Status Submitted
ProperlyCompleted Authority of destination (WSRDEST), additionally the authorities of transit (WSRTRAN) once per authority ProperlyCarriedOut is present

Signals are irreversible

A signal that has been sent can neither be retracted nor changed in its parameters. This distinguishes signals from the decision, which is updatable. Put a confirmation prompt before sending in your user interface — there is no correction afterward.

A special case that a status display must account for: for authorities of transit, the implementing act allows a tacit ProperlyCompleted if the authority has not requested additional information within the time limit and the authority of destination has marked the notification as properly completed. The status can therefore move on without a signal you would have seen.

Decision (SetDecision)
Precondition All precondition signals are present (status Satisfied)
How often One decision per authority. Each authority may update only its own, any number of times
Required fields UserCompetentAuthorityDomainId, NotificationDocumentId, Decision (with DecisionDate, DecisionType_, DecisionJustification)
Initial decision only CONSENT or OBJECTED. WITHDRAWN is allowed as an initial decision only for an authority of transit, and only if the notification has already been consented to and this authority has not yet decided
Update all three types: CONSENT, OBJECTED, WITHDRAWN

Additional information per type: via Decision.SpecificConditions, CONSENT can limit the consent to a smaller mass (ConsentValidMass), a smaller volume (ConsentValidVolume) or a lower number of shipments (ConsentValidShipmentCount), plus ValidFromDate/ValidToDate. OBJECTED carries the reasons in Decision.ObjectionDescription. A justification in DecisionJustification is always required, regardless of the type.

A capped consent is a consent with different numbers

If you ignore the SpecificConditions when reading, you plan shipments against the originally requested quantity instead of the approved one — and run into a rejection of the movement. On the intended number of shipments, see Field rules.

→ Implementation with the .NET SDK

DecisionType_ — the underscore is not a typo

The field DecisionType lives in the message DecisionType. In this case, the Protobuf generator appends an underscore to resolve the name collision. In C#, the field is therefore called DecisionType_.

For the same reason, the proto messages DecisionType and SignalStatementType collide with the SDK helper enums of the same name. In the example above, DiwassDecisionType and CompetentAuthorityDomain stand for aliases of Zedal.Sdk.Apis.Diwass.Enums.*; ToWire() comes from DiwassEnumExtensions, the short constructors Sf/DateUtc from Zedal.Sdk.Protobuf.ProtoFields.

What determines the status of the notification

The status is not the result of a single operation; it is recalculated from all decisions submitted — after every change.

Transition Trigger
Submitted → Satisfied Authority of dispatch has set ProperlyCarriedOut, authorities of destination and transit have set ProperlyCompleted
Satisfied → Consent all authorities concerned have decided, and all of them with CONSENT (tacit consent included)
Satisfied → Objected the first decision of type OBJECTED is present
Consent → Objected an authority changes its consent to OBJECTED
Objected → Consent all OBJECTED decisions have been changed to CONSENT and all authorities have decided
Objected → Satisfied all OBJECTED decisions have been changed to CONSENT, but decisions are still missing
Consent → Withdrawn an authority withdraws its consent
Withdrawn → Consent all withdrawn decisions are consents again
Submitted → Invalid an authority sets NotificationInvalid
Invalid → Submitted the same authority sets NotificationRevalidated
Submitted/Consent/Objected → Cancelled the notifier cancels

Where these status names actually appear

There is no status field in the mutations data model. In the retrieval view, however, there is: NotificationInformationType.notificationStatus is mandatory there and restricted in the schema to DRAFT, SUBMITTED, SATISFIED, CONSENT, INVALID, WITHDRAWN, OBJECTED, CANCELLED. Its counterpart on the movement is GetMovementTemplateType.movementStatus with DRAFT, ANNOUNCED, SUBMITTED, MOVING, RECEIVED, ACCEPTED, REJECTED, COMPLETED, CANCELLED, TAKE_BACK.

Both are strings with a schema-defined value set, not a C# enum. And they tell you where the process stands, not what you may do next. That is in handler.FollowupIntents — see Determining the state.

Authorities of transit do not have to decide

The consent of an authority of transit can occur tacitly: if 30 days have passed since Satisfied was reached and the authorities of dispatch and destination have consented, the notification changes to Consent, even if one or more authorities of transit have not submitted anything. This applies only if the authorities of transit concerned represent EU or EEA states.

For your application, this means: “consented” is not the same as “saw a consent decision from every authority”. If you derive consent from the presence of N decisions, you block shipments that would be permitted.

Reply to a request for change (ReplyToRequestForChangeAfterConsent)

After consent has been given, the notifier can request changes (Article 17). Every authority concerned replies to such a request.
Precondition Notification consented; a request for change is present
How often Each authority replies to the same request exactly once. The reply is not changeable
Required fields UserCompetentAuthorityDomainId, RequestForChangeAfterConsentId, AgreementChangeRouteRequest, Signature
Effect The requested change takes effect only when all affected authorities have agreed

Before sending, the SDK checks that RequestForChangeAfterConsentId is set and points to a known request; otherwise it throws ArgumentException or InvalidOperationException without sending.

UnansweredRequestForChangeAfterConsent is not a to-do list for all authorities

The property handler.UnansweredRequestForChangeAfterConsent lists requests for change to which no reply is linked yet. A request, however, expects several replies — typically from the authorities of dispatch and destination. As soon as the first authority has replied, the request drops out of this list, although the second may and must still reply.

Use the list as an indicator for “nothing has happened here at all”, not as a check whether it is still your authority’s turn.

Signals at notification level

All signals go through SubmitNotificationSignal. They are distinguished by Statement.Signal.TypeCode; the permitted values are available in the SDK as Zedal.Sdk.Apis.Diwass.Enums.SignalStatementType.

TypeCode Who When permitted Effect
ProperlyCarriedOut Authority of dispatch Status Submitted, once Precondition for the decisions
ProperlyCompleted Authorities of destination and transit after ProperlyCarriedOut, once each with the last signal, the status changes to Satisfied
NotificationInvalid any authority concerned Status Submitted Status Invalid; the document is read-only for everyone — except for the authority that invalidated it
NotificationRevalidated the same authority that invalidated it Status Invalid back to Submitted. Precondition signals that were already set are retained
RejectPreConsentedFacility any authority concerned Status Submitted, the notification was designed for pre-consented facilities the pre-consent indicator is set to false; afterward the operation is no longer available
NoPreConsentedFacilityTimeline any authority concerned as above the time limit logic falls back to the normal procedure instead of the pre-consent procedure (Article 14(16))
NotificationCancelled the notifier, not the authority Status Submitted, Consent or Objected Status Cancelled, permanently read-only, no way back
NotificationWithdrawn the notifier not specified Withdrawal of the notification. The wire value was added in April 2026 — older generated stubs do not know it
NotificationCompleted Authority not specified Completion of the notification (Article 27(1))
MovementCancelled, Annex7Cancelled see Movement — belong to the movement or Annex VII document, not to the notification

The signal record always has the same structure: number of the affected document, TypeCode, optional free text (Statement.Description — required for some types), signature of the acting person, optional attachments.

Two operations in the signal enum belong to the notifier

NotificationCancelled and NotificationWithdrawn can be reached through the same SDK method but, according to the specification, are permitted only for the notifier. They are therefore also available on the company handler NotificationDocumentHandler.SubmitNotificationSignal — there without UserCompetentAuthorityDomainId, because the notifier is not an authority. If you build the company side, you will find this under Notification (Company).

Movement: the authority interventions

At movement level there is exactly one authority operation: the take-back order.

Take-back (SetMovementTakeBack)
Who any authority concerned — not only dispatch or destination
When Movement in status Announced, Moving or Received
How often one take-back per movement. The authority that submitted it may update it any number of times
Required fields UserCompetentAuthorityDomainId, MovementIdentifier, MovementTakeBack (with Quantity, Reasons, TakeBackDate), CompetentAuthoritySignature
Effect Status changes to Take back. The lifecycle ends there — no reception, no completion anymore

SetMovementTakeBack also exists on the company handler — the order nevertheless remains an authority matter

The method exists both on AuthorityMovementDocumentHandler and on MovementDocumentHandler, and the SDK’s permission matrix allows the take-back intents (CreateMovementTakeBack, UpdateMovementTakeBack) for the role Notifier. According to the DIWASS specification, however, the take-back is an operation of the authorities concerned.

This shows in the payload: UserCompetentAuthorityDomainId is a required field in MovementTakeBackDocumentType, and so is CompetentAuthoritySignature. Without an authority context, the record cannot be filled. Do not rely on the permission matrix here; rely on handler.FollowupIntents — that is the server’s view.

SubmitMovementSignal is the notifier’s cancellation

The signal enum has exactly one value at movement level: MovementCancelled. According to the specification, only the notifier may set it, and only as long as the movement is not yet underway:
Who the notifier
When Status Draft or Announced — no longer after Moving
Effect Status Cancelled

The method is available on both handlers. For the authority side, it is only relevant when an authority submits the signal on behalf of the notifier; UserCompetentAuthorityDomainId is therefore optional in MovementSignalDocumentType.

How an authority is identified

In DIWASS, authorities are not an operator party. They have no OperatorInternalId, do not appear in any of the party slots of the submission and therefore cannot be derived from a document either. For the SDK’s role inference, this means: Role.Authority must be passed explicitly.

An authority is identified on three different levels — telling them apart is the number one source of errors:

Level Field Values
Role in the procedure UserCompetentAuthorityDomainId on every authority document WSRDISP (dispatch), WSRTRAN (transit), WSRDEST (destination) — SDK: CompetentAuthorityDomain
Organization CompetentAuthorityType with PartyUuid and CompetentAuthorityId business authority code, e.g. DE014
Location in the process CompetentAuthority within ExportState, ImportState and each TransitState of the submission exactly one authority per country concerned

The third row is the reason why an authority without its own party slot can still be “concerned”: it is attached to the country, not to the list of parties. If you want to determine the authorities concerned for a notification, read them from the export, import and transit states.

The domain codes do not belong in the authority directory

WSRDISP/WSRTRAN/WSRDEST are values of the notification model. The authority directory has a different role field with its own code list. Value tables: Code lists → Authority domain.

You can search for authorities via the directory.

→ Implementation with the .NET SDK

The directory does not tell you who may act as an authority of transit

ListAuthorities and FindActivities return the WSR authorities of a country, but not which notification domain an authority covers. Which authority is permitted as an authority of transit is something you have to know from the business domain. AUTHORITY-ID-NOT-FOUND is therefore a statement about competence, not about existence — details under Field rules → Competence of the authority of transit.

Also note: in the document, the country code is three-digit numeric (056), whereas the directory lookup uses alpha-2 (BE). A numeric code returns zero hits there without an error message. See Code lists.

Acting “on behalf of” (OnBehalfOfCA)

Not every authority is connected to DIWASS, and not every party works in the EU system. For these cases, almost every authority document carries an optional OnBehalfOfCa (OnBehalfCAType):

Field Required Content
CompetentAuthorityId yes Authority on whose behalf the action is taken
CompetentAuthorityDomainId yes WSRDISP, WSRTRAN or WSRDEST
CountryId no Country of the represented authority

Available on AcknowledgementDocumentType, DecisionDocumentType, RequestInformationDocumentType, ReplyToRequestForChangeAfterConsentDocumentType, NotificationSignalDocumentType and MovementSignalDocumentType — not on MovementTakeBackDocumentType.

UserCompetentAuthorityDomainId remains the role of the acting authority; OnBehalfOfCa names the represented one. The more general type OnBehalfOfType additionally covers the representation of a country or an operator and allows exactly one of the three branches.

What reaches you

The value of this page for a company integration lies in this table: which authority operation changes what in your document.

Authority operation What you see What changes for you
Acknowledgment of receipt new version with an entry in acknowledgement nothing — an acknowledgment is not consent
Request for additional information entry in requestInformation, new follow-up intents It is your turn. And: the notification is editable again
ProperlyCarriedOut / ProperlyCompleted entry in signals, changed follow-up intents Once all are set and no request for additional information is open, the change window is closed
Decision entry in decisions per authority Only when all are present (or apply tacitly) may you create movements. Observe SpecificConditions
Reply to a request for change entry in replyRequestForChangeAfterConsent per authority The change takes effect only when all have agreed
NotificationInvalid notificationStatus = INVALID Your notification is read-only until the same authority revalidates it
Take-back order takeBack set on the movement The movement has ended. No reception, no completion anymore

Two points that are regularly underestimated:

Changes made by others take time — and the inbox import

Between an authority’s push to DIWASS and its appearance in the ZEDAL data store, 100 to 150 seconds have been measured. Until then, reloading returns the original document without the authority block. The inbox import is the delivery path here, not mere cleanup — without it, the new version does not appear. See Calls and synchronization.

Do not derive the state from list lengths

Neither “as many decisions as authorities concerned” nor “requestInformation longer than replyRequestInformation” yields a reliable state: consents can occur tacitly, and replies to requests for additional information end up in the same list as the requests themselves. Evaluate handler.FollowupIntents — that list comes from the server. See Determining the state.

What’s next