DCSA Standards Public Reference / Standards / Releases / Arrival Notice / Arrival Notice v1

DCSA AN 1.0.1 - Implementation Guide

Contents

What this guide is for

Use this guide to turn the Arrival Notice 1.0.1 standard into an implementation plan. It focuses on choices that an Arrival Notice Publisher or Arrival Notice Subscriber must make and document. It does not replace the OpenAPI, conformance scenarios, information model, API design and implementation guidelines, or Technical Appendix.

Prerequisites

Complete these steps before designing or building the implementation. They are part of the implementation process, not optional background reading.

Understand the standard context

  • Read the Introduction and Purpose and Scope for an overview of Arrival Notice.

Identify roles and user stories

  • Study the User Stories to understand the Arrival Notice Publisher and Arrival Notice Subscriber roles, the types of businesses that may participate in each role, and the needs that each user story supports.
  • List the counterparties with which your organization will exchange arrival notices. For each relationship, identify the role played by your organization and the role played by the counterparty.
  • An organization may implement more than one role. Determine the role separately for each interaction; do not use the organization’s business type as a substitute for its Arrival Notice role.
  • For every role in your implementation scope, select the relevant user stories and their corresponding use cases.

Select interaction types

  • Decide whether each Publisher-Subscriber interaction will use retrieval of complete arrival notices through GET /arrival-notices, delivery of complete arrival notices through POST /arrival-notices, delivery of lightweight notifications through POST /arrival-notice-notifications, or a supported combination.
  • Decide which Arrival Notice variants and optional content the implementation will support. Record the business reason for any published conformance profile, variant, or optional content left outside the implementation scope.

Understand the use cases and process

  • Study the Use Cases, focusing on the use cases selected for each implemented role.
  • Understand what is outside the scope of Arrival Notice and decide whether separate, non-standard functionality is needed for those requirements.
  • Review the Business Process Model and map the selected Arrival Notice interactions to your organization’s processes.
  • Use the Endpoint Overview to map each selected use case and role to the relevant endpoint.

Understand the data structures

  • Consult the Data Overview for the data objects and attributes supported by Arrival Notice.
  • Review the Arrival Notice Information Model and map the standard structures to your organization’s data structures.
  • Use the OpenAPI and generated data artifacts as the source for endpoint, payload, schema, coded-value, and attribute requirements.

Understand the implementation guidance

  • Read the Implementation Guidelines section of the DCSA API Design and Implementation Guidelines.

  • Study the Technical Appendix:

    • understand pull, complete-notice push, and lightweight-notification push, then select the interaction model appropriate to each Publisher-Subscriber relationship;
    • if implementing GET /arrival-notices in either role, understand its filtering, pagination, and optional-response controls and design the implementation accordingly; and
    • understand error handling and feedback, then define the supported behavior for each interaction.

  • Study the Conformance Scenarios and Validations and identify the scenarios relevant to each implemented role, endpoint, and supported Arrival Notice profile.

Understand migration when applicable

  • If replacing a proprietary arrival-notice exchange or an implementation based on an earlier DCSA release, compare the existing data, process, and API behavior with Arrival Notice 1.0.1 before designing the migration.
  • In particular, account for the Arrival Notice 1.0.1 additions, including placeOfBLIssue, additional seal information, facilityName, and addressLines, where they are relevant to the implemented profile.

What Arrival Notice unifies—and what it does not

Arrival Notice provides a common vocabulary, payload structure, API surface, and set of business interaction patterns for exchanging arrival information. It allows different parties to exchange structured arrival notices without first inventing a proprietary notice model for every integration.

That common model is not a promise that every implementation behaves the same. In particular, Arrival Notice does not guarantee:

  • that every Publisher supports every optional filter on GET /arrival-notices;
  • that every Publisher supplies every optional section or attribute in an arrival notice;
  • that every implementation supports all published conformance profiles or variants;
  • uniform pagination, retention, ordering, retry, batching, or delivery-timing behavior;
  • that lightweight notifications contain the complete notice or replace retrieval of the complete notice;
  • a standard registration, subscription, entitlement, or security arrangement between counterparties; or
  • a standard mechanism for cancelling or retracting a previously issued arrival notice.

An implementation should use the common parts of Arrival Notice directly and make its remaining capabilities and limitations visible. A Subscriber integrating with multiple Publishers should expect one common notice model with Publisher-specific operational profiles, not identical Publisher behavior.

Plan the implementation

Work through these steps before building an endpoint or integration:

  1. Choose your role. Decide whether the implementation acts as an Arrival Notice Publisher, Arrival Notice Subscriber, or both.
  2. Choose the interaction model for each connection. Select pull, complete-notice push, lightweight-notification push, or a supported combination after reviewing the trade-offs in the Technical Appendix.
  3. Define supported scope. Record the supported conformance profiles, notice variants, filters, optional content, transport-document and equipment references, counterparties, and business contexts.
  4. Define notice lifecycle behavior. Decide how newly issued and subsequently reissued notices are identified, stored, compared, and presented. Do not claim standard update, cancellation, or retraction semantics that the API does not define.
  5. Make actual operational behavior visible. Document filtering, pagination, response controls, batching, retries, feedback, security, availability, and support behavior where known. Agree bilateral details where the integration requires them, without implying that every counterparty can make the same choices.

Role and interaction-model responsibilities

For pull, the Publisher exposes GET /arrival-notices and returns authorized notices within the Publisher’s supported scope. The Subscriber calls the endpoint and maintains the state needed to retrieve and process notices.

For complete-notice push, the Publisher sends relevant notices to the Subscriber’s POST /arrival-notices endpoint. The Subscriber exposes and operates that endpoint and safely processes the delivered notices.

For lightweight-notification push, the Publisher sends notifications to the Subscriber’s POST /arrival-notice-notifications endpoint. The Subscriber exposes and operates that endpoint and uses the notification according to the agreed process, which may include retrieving or locating the related complete notice.

The registration, subscription, commercial arrangement, or entitlement model that determines which parties exchange which notices is outside the Arrival Notice API contract. Agree and document it separately.

One organization may implement several roles and interaction models. Treat each interaction separately and apply the checklist for the role played in that interaction.

Notice issue time and lifecycle behavior

An Arrival Notice includes transportDocumentReference, typeLabel, issueDateTime, and versionLabel. These fields distinguish the notice, its technical versions, and its optional business-facing version label.

The standard defines the following identity and precedence rules:

  • An arrival notice, including all its versions, is uniquely identified by the combination of transportDocumentReference and typeLabel.
  • A particular version of an arrival notice is uniquely identified by the combination of transportDocumentReference, typeLabel, and issueDateTime.
  • Among versions with the same transportDocumentReference and typeLabel, the version with the newer issueDateTime overrides the version with the older issueDateTime, regardless of versionLabel.
  • “Newer” refers exclusively to issueDateTime, not to when a notice was pushed, retrieved, received, or processed.

Notice correlation and precedence

Subscribers should correlate versions using both transportDocumentReference and typeLabel, then use issueDateTime to determine their precedence. Notices with different typeLabel values are separate arrival notices and do not override one another, even when they have the same transportDocumentReference.

A version that is received or retrieved later does not override another version merely because it arrived later. It overrides an older version only when it has the same transportDocumentReference and typeLabel and a newer issueDateTime. Implementations should preserve overridden versions where required for audit, dispute handling, or regulatory purposes.

Corrections and withdrawal

Arrival Notice 1.0.1 does not define a dedicated correction, cancellation, or retraction endpoint. When a Publisher issues a corrected version with the same transportDocumentReference and typeLabel and a newer issueDateTime, the standard precedence rule applies. This override does not by itself mean that the earlier version has been canceled or retracted.

Subscribers should not assume that the absence of a notice from a later retrieval result means that an earlier notice has been withdrawn. Retention windows, authorization, filtering, and Publisher-specific behavior can all affect retrieval results.

Arrival Notice Publisher checklist

For every supported interaction:

  • Use a consistent and predictable typeLabel so that Subscribers can identify versions of the same arrival notice.
  • When issuing a newer version, retain its transportDocumentReference and typeLabel and provide a newer issueDateTime.
  • Do not use versionLabel or delivery order to imply or determine technical version precedence.

Publisher exposing GET /arrival-notices

  • Implement retrieval by transportDocumentReferences as required by the OpenAPI and conformance scenarios.
  • Support additional filters to the extent declared by the Publisher’s supported conformance profile and implementation capability.
  • Map supported retrieval patterns and filters to the internal data model. Design any indexing, orchestration, or aggregation needed to serve them reliably at the required scale.
  • Apply authorization and entitlement filtering before returning notices.
  • Implement cursor-based pagination and document page-size, cursor, ordering, stability, and known limitations.
  • Implement includeVisualization and removeCharges according to the OpenAPI where those controls are supported and applicable.
  • Identify where the response is assembled and document how duplicate, conflicting, or differently timed source data is handled.
  • Return HTTP 200 with an empty arrivalNotices array when a valid request produces no matching or visible notices; do not return 404 merely because a notice is unavailable.
  • Treat an unknown transport document reference and a transport document for which no arrival notice is yet available as successful empty retrievals unless another request-level error applies.
  • Map malformed values, unsupported rejected filters, excessive reference counts, invalid date ranges, invalid cursors, authentication failures, authorization failures, unsupported API versions, and temporary service failures to appropriate request-level HTTP responses.
  • For GetArrivalNoticesError, return at least one feedbackElement with severity ERROR, use actionable messages, and use propertyPath only where it can truthfully identify a property in a JSON request message.
  • Test and document default behavior, optional filter behavior, empty results, error responses, retention, and service expectations.

Publisher sending to POST /arrival-notices

  • Define which complete arrival notices are sent to each Subscriber and how that scope is managed.
  • Define which supported profile or variant is sent for each business context.
  • Choose batching and payload behavior that the Publisher can support. Document relevant limits and known behavior for Subscribers where practical.
  • Choose recovery behavior that fits the Publisher’s infrastructure, such as retry, backoff, buffering, or operational replay, and document the resulting duplicate or loss risks.
  • Define flow control for bursts and slow Subscribers, including any throttling, rate limits, prioritization, or buffering that the implementation supports.
  • Avoid creating duplicate business effects when the same notice is delivered more than once.
  • Interpret Subscriber feedback consistently and define which failures are retryable.
  • Document authentication, authorization, transport security, availability, monitoring, and incident procedures.

Publisher sending to POST /arrival-notice-notifications

  • Define which notices cause a lightweight notification to be sent and which Subscribers receive it.
  • Populate the notification fields from the related arrival notice consistently, including transportDocumentReference and issueDateTime.
  • Define whether a notification means that a complete notice is immediately available, has already been pushed, or can be retrieved through another agreed channel.
  • Define retry, buffering, duplicate-delivery, and ordering behavior.
  • Do not treat a successful notification delivery as proof that the Subscriber has retrieved or completed processing of the full arrival notice.
  • Document the relationship between notification delivery and complete-notice availability.

Arrival Notice Subscriber checklist

For every supported interaction:

  • Correlate versions using the combination of transportDocumentReference and typeLabel.
  • Determine version precedence using issueDateTime, not the time or order in which versions were pushed, retrieved, received, or processed.
  • Treat the newer issueDateTime as overriding the older one only when transportDocumentReference and typeLabel are the same, and preserve overridden versions where required for audit or other obligations.

Subscriber calling GET /arrival-notices

  • Maintain the transport document references and, where used, the equipment, vessel, voyage, service, port, and date information needed to construct requests.
  • Define how the implementation selects required and optional filters for each use case and Publisher integration.
  • Use only filter combinations supported by the Publisher’s declared capability and the applicable conformance profile.
  • Process cursor-based pagination consistently and protect retrieval state from partial processing.
  • Apply includeVisualization and removeCharges only where the requested behavior is needed and supported.
  • Distinguish an HTTP 200 response with an empty arrivalNotices array from a failed, rejected, or incomplete retrieval.
  • Treat an empty successful response as meaning only that no matching and visible notice was returned; do not infer whether the transport document is unknown, the notice is not yet available, the notice is outside retention, or access is restricted.
  • Parse GetArrivalNoticesError.feedbackElements, route ERROR, WARN, and INFO appropriately, and do not rely on human-readable message text as a standardized domain error code.
  • Do not infer that every matching notice exists or is visible: the Publisher may further restrict results according to authorization, entitlement, retention, or supported scope.
  • Define retry and recovery behavior for failed or interrupted retrieval, distinguishing retryable service failures from request problems that require correction.
  • Document Publisher-specific assumptions, monitoring, replay, and escalation.

Subscriber exposing POST /arrival-notices

  • Operate a secure, externally reachable endpoint for authorized Publishers, including the required routing, DNS, certificates, and network controls.
  • Define the expected conformance profiles, notice variants, transport-document scope, and business context for each Publisher interaction.
  • Validate one-notice and multi-notice deliveries without assuming a universal batch size.
  • Make processing idempotent or duplicate-tolerant so repeated delivery does not create repeated business effects.
  • Define when an HTTP request is considered accepted and how partial or asynchronous processing failures are handled internally.
  • Buffer or queue work where useful to handle bursts, and document the limits beyond which delay or loss may occur.
  • Preserve transport-document, issue-time, source, and audit information required by the Subscriber’s implementation and agreements.
  • Document availability, response behavior, feedback, retry expectations, monitoring, and incident procedures.

Subscriber exposing POST /arrival-notice-notifications

  • Operate a secure, externally reachable endpoint for authorized Publishers.
  • Validate the notification payload and correlate it using transportDocumentReference, issueDateTime, and any supplied equipment or location information.
  • Define whether the notification triggers retrieval, reconciliation with a previously pushed notice, user notification, or another internal process.
  • Make processing duplicate-tolerant and do not assume notifications arrive exactly once or in issue-time order.
  • Define behavior when the related complete notice cannot be found or retrieved.
  • Document availability, response behavior, retries, monitoring, and escalation.

Lightweight notification checklist

A lightweight notification is not a complete arrival notice. Design the notification and complete-notice processing paths independently, then document how they interact.

  • State which complete-notice interaction is used with notifications: pull, complete-notice push, another agreed channel, or a combination.
  • State whether the notification is sent before, with, or after the complete notice becomes available.
  • Preserve the transportDocumentReference and issueDateTime needed to correlate the notification with the complete notice.
  • Define how duplicate notifications are recognized and handled.
  • Define how the Subscriber behaves when notifications arrive out of order.
  • Define how notification retries interact with complete-notice retrieval or delivery.
  • Document expected notification delay, complete-notice availability, retention, and replay behavior.
  • Do not represent notification receipt as confirmation that the complete notice has been accepted or acted upon.

Arrival Notice does not guarantee end-to-end synchronization between a lightweight notification and the complete notice. Subscribers should not assume that every notification is followed by a successful complete-notice exchange unless the Publisher’s documented behavior or a bilateral agreement says so.

Capability profile and implementation behavior

Document the following where it is relevant and known. The purpose is to make actual behavior visible, not to imply that every implementation can support the same technical choices. A Publisher can publish this information as its capability profile. A multi-Publisher Subscriber can maintain the same information for each integration and use it to drive source-specific configuration.

  • Scope: supported roles, conformance profiles, notice variants, optional sections, references, geographies, and business contexts.
  • Exchange: pull, complete-notice push, lightweight-notification push, or supported combinations; endpoint ownership; onboarding and registration process.
  • Retrieval: supported filters and filter combinations, default behavior, pagination, ordering, cursor behavior, and retention.
  • Delivery: trigger timing, maximum batch or payload size, latency, throttling, and ordering assumptions.
  • Notice lifecycle: implementation of the standard identity and precedence rules, duplicate handling, replay, correction, cancellation, and withdrawal behavior.
  • Response controls: behavior of includeVisualization and removeCharges, including any profile-specific limitations.
  • Feedback: success criteria, empty-result behavior, HTTP status mapping, supported request-validation cases, partial failures, retryable errors, feedback payloads, message conventions, and escalation.
  • Security: authentication, authorization, transport protection, certificates, and entitlement rules.
  • Operations: availability, monitoring, auditability, incident contacts, recovery objectives, and change notice.

Coverage and conformance

Arrival Notice supports complete arrival notices and lightweight notifications. The published conformance scenarios qualify conformance by role, endpoint, and supported profile, including the BASIC, FREIGHTED, and FREE_TIME profiles where applicable.

The base standard does not guarantee that every Publisher supports every optional filter or includes every optional notice section. Publishers should publish a clear coverage statement. Subscribers should evaluate that statement against their use cases before relying on a particular filter, profile, field, visualization, charge treatment, or service level.