DCSA Standards Public Reference / Standards / Releases / Arrival Notice / Archive / Arrival Notice v1.0.1

DCSA AN 1.0.1 - Technical Appendix

Archived copy: This immutable copy preserves Arrival Notice v1.0.1. View the current v1 documentation.

Contents

Arrival Notice Push vs. Pull

The DCSA Arrival Notice standard supports complementary interaction models for exchanging arrival notices between Arrival Notice Publishers and Arrival Notice Subscribers: a pull model, a complete-notice push model, and a lightweight-notification push model. These models describe which party initiates the transfer and which party exposes the receiving endpoint.

Conceptual difference

In the pull model, the Arrival Notice Subscriber retrieves complete arrival notices from the Arrival Notice Publisher. The flow of notices is therefore from Publisher → Subscriber, but initiated by the Subscriber. The Publisher exposes a GET /arrival-notices endpoint, and the Subscriber calls this endpoint to retrieve relevant notices.

In the complete-notice push model, the Arrival Notice Publisher sends complete arrival notices to the Arrival Notice Subscriber. The flow of notices is again from Publisher → Subscriber, but initiated by the Publisher. The Subscriber exposes a POST /arrival-notices endpoint, and the Publisher delivers notices to this endpoint as they become available.

In the lightweight-notification push model, the Arrival Notice Publisher sends a smaller notification object to the Arrival Notice Subscriber. The Subscriber exposes a POST /arrival-notice-notifications endpoint. The notification identifies the relevant transport document and supplies selected timing, equipment, and location information, but it is not a replacement for the complete arrival notice.

All three models support the exchange of arrival information, but they differ in which party initiates the transfer, which party must implement an inbound endpoint, and whether the complete notice or only a notification is transferred.

Choosing between push and pull

Adopters should choose between pull, complete-notice push, and lightweight-notification push based on a combination of technical capabilities, operational preferences, business requirements, and counterparty constraints.

Key considerations include:

  • Ability to implement and expose endpoints

    • Pull model: requires the Arrival Notice Publisher to expose a GET /arrival-notices endpoint. The Subscriber only needs to make outbound requests.
    • Complete-notice push model: requires the Arrival Notice Subscriber to expose a POST /arrival-notices endpoint that can receive inbound requests from the Publisher.
    • Lightweight-notification push model: requires the Arrival Notice Subscriber to expose a POST /arrival-notice-notifications endpoint. A separate supported process is still needed for the complete arrival notice.

  • Inbound vs outbound integration capabilities

    • Organizations that cannot or prefer not to expose externally accessible APIs will typically choose the model that does not require them to implement an inbound endpoint.
    • Organizations that can reliably operate inbound APIs can support complete-notice push, lightweight-notification push, or both, depending on their role and integration needs.

  • Control over data retrieval and delivery

    • In the pull model, the Subscriber controls when notices are retrieved and which supported filters are applied.
    • In the push models, the Publisher controls when complete notices or notifications are sent.

  • Payload and processing needs

    • Complete-notice push transfers the full arrival-notice payload in the delivery request.
    • Lightweight-notification push transfers only the notification payload and therefore requires the parties to define how the Subscriber obtains or relates the complete notice.

  • Counterparty capabilities

    • Integration design must account for the capabilities of both parties. If one party cannot support an inbound endpoint, the corresponding push or pull model may not be feasible.
    • In multi-party ecosystems, supporting more than one model may be necessary to ensure interoperability.

Pros and cons of each model

Arrival Notice Pull Model

In the arrival notice pull model, the Subscriber retrieves notices from the Publisher’s GET /arrival-notices endpoint.

Advantages

  • Simpler for Arrival Notice Subscribers because they do not need to host an inbound API.
  • Greater control over timing and frequency of data retrieval.
  • Allows the Subscriber to retrieve notices using supported business filters.
  • More tolerant of temporary downtime on the Subscriber side because failed requests can be retried.

Disadvantages

  • Can introduce latency between notice availability and retrieval.
  • Can result in unnecessary requests when no matching notices are available.
  • Requires the Subscriber to manage request criteria and cursor-based pagination.
  • Results can depend on Publisher-specific filter support, defaults, retention, authorization, and entitlement behavior.

Complete Arrival Notice Push Model

In the complete arrival notice push model, the Publisher sends notices to the Subscriber’s POST /arrival-notices endpoint.

Advantages

  • Enables timely delivery of complete arrival notices.
  • Eliminates the need for the Subscriber to poll for notices.
  • Transfers a list of complete structured arrival notices in one interaction.

Disadvantages

  • Requires Subscribers to implement and operate a reliable, secure inbound endpoint.
  • Increases operational complexity, including availability, scaling, security, and firewall configuration.
  • Requires handling of delivery failures, retries, repeated delivery, and duplicate business effects.
  • Reduces Subscriber control over delivery timing and load.

Lightweight Notification Push Model

In the lightweight-notification push model, the Publisher sends notifications to the Subscriber’s POST /arrival-notice-notifications endpoint.

Advantages

  • Enables timely notification that relevant arrival information is available or has been issued.
  • Uses a smaller payload than a complete arrival notice.
  • Can prompt retrieval or reconciliation without repeatedly polling for all notices.

Disadvantages

  • Requires Subscribers to implement and operate a reliable, secure inbound endpoint.
  • Does not itself provide the complete arrival notice.
  • Requires the parties to define how the notification relates to complete-notice retrieval or delivery.
  • Requires handling of retries, duplicate notifications, ordering, and cases where the related complete notice is not available.

The standard is designed to support pull, complete-notice push, and lightweight-notification push, allowing flexibility across different integration scenarios.

A pragmatic approach is:

  • Start with the pull model where faster onboarding and outbound-only Subscriber integration are important.
  • Introduce complete-notice push where timely delivery of the full notice is important and the Subscriber can operate an inbound endpoint.
  • Introduce lightweight-notification push where timely prompting is useful but the complete notice is retrieved or handled separately.
  • Support more than one model where feasible to accommodate different counterparties.

The final choice should balance technical feasibility, operational readiness, payload requirements, and business requirements for timeliness, while ensuring interoperability across the Arrival Notice ecosystem.

Arrival Notice Filtering in GET /arrival-notices

This section explains how filtering works in the GET /arrival-notices endpoint and how Arrival Notice Publishers should interpret the filtering requirements of the standard.

Transport document and equipment filters

The Arrival Notice standard is designed primarily to support retrieval of notices for one or more transport documents and, where supported, for one or more pieces of equipment.

The primary filters are:

  • transportDocumentReferences
  • equipmentReferences

Retrieval by transportDocumentReferences is the core retrieval pattern. The parameter accepts one or more transport document references and enables the Subscriber to retrieve the notices it is authorized to receive for those references.

The equipmentReferences filter supports retrieval based on equipment identifiers where the Publisher supports that filter under its declared implementation profile.

Required support for filter combinations

Arrival Notice Publishers need to distinguish between the universally required retrieval behavior and additional filtering capabilities.

The OpenAPI exposes multiple optional query parameters. The conformance scenarios determine which behavior is required for a conforming implementation and which additional behavior belongs to a supported profile or Publisher capability. A Publisher should not claim support for a filter or filter combination that its implementation cannot process consistently.

For every supported filter combination, the Publisher should think through how the filters map to its internal data model, how transport documents, equipment, voyages, services, ports, and dates are resolved, and how the relevant notices are retrieved efficiently. Some implementations may require aggregation, denormalization, or a dedicated query layer.

Voyage, service, location, and date filtering

In addition to transport document and equipment references, the OpenAPI defines filters for:

  • portOfDischarge
  • vesselIMONumber
  • vesselName
  • carrierImportVoyageNumber
  • universalImportVoyageReference
  • carrierServiceCode
  • universalServiceReference
  • portOfDischargeArrivalDateMin
  • portOfDischargeArrivalDateMax

These filters allow a Subscriber to narrow retrieval using voyage, service, discharge-port, and arrival-date information where the Publisher supports the relevant capability.

Publishers should apply each supported filter according to the schema and published conformance requirements. Subscribers should not assume that every Publisher supports every one of these filters merely because it appears in the OpenAPI.

For the arrival-date range:

  • portOfDischargeArrivalDateMin returns only arrival notices with a portOfDischargeArrivalDate on or after this date
  • portOfDischargeArrivalDateMax returns only arrival notices with a portOfDischargeArrivalDate on or before this date
  • Publishers should document the treatment of boundaries and any restrictions on the supported date range.

Response-content controls

The GET /arrival-notices endpoint includes two parameters that affect returned content rather than selecting notices:

  • includeVisualization
  • removeCharges

includeVisualization allows the Subscriber to request the arrival notice visualization where the notice and implementation support it.

removeCharges allows the Subscriber to request a response without charge information. This can be relevant where the same underlying notice is used in contexts with different authorization or disclosure requirements.

Publishers should implement these controls consistently and should document any limitations. Subscribers should not treat either control as an entitlement override. Authorization and business rules still apply.

Pagination with limit and cursor

The endpoint uses cursor-based pagination through:

  • limit
  • cursor

The limit parameter requests a maximum number of results. The Publisher may apply an implementation-specific maximum and should document that behavior.

The cursor parameter identifies the next result position supplied by the Publisher. Subscribers should treat the cursor as an opaque value and return it unchanged in the next request. They should not parse it or construct their own cursor values. Subscribers must keep alongside the cursor all the original query parameters from the request that retrieved the first page, in order to allow either a stateful or a stateless implementation of the pagination mechanism by the arrival notice publisher.

Publishers should design pagination so that Subscribers can process pages consistently. They should document page-size behavior, ordering, cursor validity, result stability, and what happens when data changes between page requests.

Meaning of “optional” query parameters

When the specification describes a query parameter as optional, it means that the Subscriber is not required to include it in every request. It does not automatically mean that every Publisher may ignore the parameter.

The required level of Publisher support depends on the OpenAPI, the published conformance scenarios, and the capability profile claimed by the Publisher.

Implementers should therefore distinguish between:

  • parameters that a Subscriber may omit;
  • parameters that a Publisher must support for the applicable conformance profile; and
  • additional parameters that a Publisher supports as declared capability.

Publishers should reject (with an HTTP 400) unsupported or invalid filter usage consistently rather than silently returning misleading results. Where a parameter is adjusted or ignored under behavior permitted by the implementation, the response feedback should make that behavior visible.

Authorization-based filtering and defaults

Filtering is not limited to the explicit query parameters in the request. Arrival Notice Publishers should also apply filtering based on the identity and authorization of the Subscriber.

This means that the result set should not be determined solely by the requested references and optional filters. It should also be limited to notices that the authenticated Subscriber is allowed to receive. Depending on the Publisher’s implementation, this may be based on registration data, contractual scope, document-party relationships, customer relationships, or other entitlement rules outside the scope of the standard.

As a result:

  • two Subscribers sending the same query may legitimately receive different results;
  • the Publisher should treat authorization as an additional filter on top of the request parameters; and
  • the Publisher should design and document this behavior clearly so that Subscribers understand that the API is not a neutral search interface over all arrival notices.

Where Publishers apply implementation-specific defaults or limits, those defaults should be documented clearly. Defaults can materially affect the notices returned and therefore need to be transparent to Subscribers.

Error Handling and Feedback

This section provides guidance on how to implement error handling and feedback mechanisms in the DCSA Arrival Notice API. It distinguishes between request-level errors and message-level feedback, and clarifies how both should be used consistently for GET /arrival-notices, POST /arrival-notices, and POST /arrival-notice-notifications.

Request-Level Error Handling

The standard relies on HTTP status codes to indicate whether an API request was successfully processed at a technical and request-validation level. It does not define a catalogue of domain-specific error codes.

For GET /arrival-notices, HTTP 200 means that the request was valid and was processed successfully. It does not mean that an arrival notice was found. If no arrival notices match the request criteria, the OpenAPI requires a normal HTTP 200 response with an empty arrivalNotices array. An unknown transport document reference and a transport document for which an arrival notice is not yet available therefore normally produce the same successful empty result, provided that the request itself is valid.

A Publisher may be unable to distinguish externally between several reasons for an empty result, including:

  • the transport document reference does not exist;
  • an arrival notice has not yet been issued or made available;
  • the notice is outside the Publisher’s retention period;
  • the authenticated Subscriber is not entitled to receive the notice; or
  • another explicit or implicit filter excludes the notice.

The standard does not require the Publisher to disclose which of these reasons applies. Using the same empty-result behavior can also avoid revealing whether a transport document or notice exists to a party that is not entitled to know.

HTTP 400 should be used when the request cannot be processed because the request itself is invalid or because the Publisher has chosen to reject unsupported request behavior. Examples include:

  • a missing input that the Publisher requires for the supported retrieval pattern;
  • a malformed query-parameter value;
  • more transportDocumentReferences or equipmentReferences than the Publisher’s documented maximum;
  • an unsupported query parameter or unsupported filter combination that the Publisher chooses not to ignore;
  • an invalid date or date range;
  • an invalid, expired, reused, or inconsistent cursor where the Publisher rejects that use; or
  • unsupported API-version behavior.

Other HTTP status codes should be used according to their normal request-level meaning. For example, authentication failures normally use 401, authorization failures normally use 403, and unexpected Publisher-side failures normally use an appropriate 5xx status. The OpenAPI defines a default error response rather than prescribing a separate status code for every failure condition.

Implementers should therefore:

  • Treat request-level errors as applying to the entire request, not to individual notices or notifications within a request.
  • Return a structured error response containing one or more feedback elements explaining why the request could not be processed.
  • Do not return HTTP 404 merely because no matching arrival notice is available.
  • Distinguish a successful empty retrieval from a failed, rejected, or incomplete retrieval.

Message-Level Feedback

In addition to request-level errors, the standard supports feedback elements that provide information about how a request or individual messages were processed.

A feedback element includes:

  • A severity, such as ERROR, WARN, or INFO.
  • A human-readable message.
  • A property path indicating, if applicable, the specific message and property to which the feedback applies.

GetArrivalNoticesError is the schema object used as the response body when a GET /arrival-notices request is not processed successfully. In the OpenAPI specification, it is referenced by the endpoint’s default response; it is not a property of another object. The object contains feedbackElements. At least one feedback element with severity ERROR is expected, and lower-severity feedback elements may also be included. The error response should contain enough information for the Subscriber or an operator to understand and correct the request without exposing sensitive internal implementation details.

Implementers should:

  • use a clear and actionable message for each distinct problem;
  • include more than one feedback element when several independent problems need to be reported;
  • use propertyPath only when the feedback concerns a specific property in a JSON request message;
  • avoid inventing a JSONPath for a query parameter, because propertyPath is defined as a JSONPath within the request message and a GET query has no JSON request body; and
  • document any stable message conventions or implementation-specific error identifiers outside the standard response fields when operational processing depends on them.

This mechanism is used differently depending on the endpoint.

Feedback on POST /arrival-notices and POST /arrival-notice-notifications (Push)

When an Arrival Notice Publisher sends complete notices or lightweight notifications to an Arrival Notice Subscriber, the Subscriber may return feedback elements indicating:

  • Messages that could not be processed.
  • Messages that were processed with warnings or unexpected conditions.
  • Informational messages about how the request was handled.

This feedback may apply to:

  • The entire request as general feedback.
  • Specific notices or notifications within the request by using property paths.

Importantly:

  • A push request may still return a successful HTTP response even if some messages were not processed successfully, according to the response contract.
  • Feedback elements should be used to communicate partial success or message-level issues rather than rejecting the entire request when request-level processing succeeded.

Implementers should use the exact status and response behavior defined in the OpenAPI and should not infer acceptance of every item from the HTTP status alone.

Feedback on GET /arrival-notices (Pull)

When an Arrival Notice Subscriber retrieves notices from an Arrival Notice Publisher, feedback elements may be included in a successful response to indicate:

  • how the query was interpreted;
  • whether certain filters or controls were ignored, adjusted, or could not be applied as requested; and
  • any unexpected but non-fatal condition affecting the result.

A Publisher may include INFO or WARN feedback with an empty successful result when it can provide useful and truthful processing information. It should not claim that a bill of lading does not exist or that an arrival notice has not yet been issued unless it can make that distinction reliably and is permitted to disclose it.

This feedback applies to the request and its processing, not normally to the validity of individual arrival notices being returned.

Severity and Processing of Feedback

The severity field is intended to be interpreted programmatically by the receiving system.

Typical usage includes:

  • Routing ERROR messages for immediate attention or corrective action.
  • Logging or monitoring WARN messages.
  • Optionally recording or ignoring INFO messages according to implementation needs.

Implementers should design their systems so that feedback can be:

  • Parsed automatically.
  • Routed appropriately, for example to logs, monitoring systems, or human operators.
  • Correlated with the originating request and, where applicable, the affected notice or notification.

Synchronous Nature of Feedback

All feedback in the standard is synchronous:

  • Feedback is returned only as part of the response to a GET /arrival-notices, POST /arrival-notices, or POST /arrival-notice-notifications request.
  • There is no standard mechanism for asynchronous follow-up feedback after a request has been completed.

This means that:

  • Issues known during request processing should be communicated in the immediate response.
  • There is no standard way to later notify a counterparty about problems discovered after initial processing.

Implementations that require later operational feedback need a separate bilateral process outside the Arrival Notice API contract.

Implementation Considerations

Because feedback handling is flexible in the standard, implementers should make explicit decisions and document them clearly.

In particular, each adopter should define:

  • Whether its implementation produces feedback elements, and under which conditions.
  • Whether its implementation processes received feedback, and how.
  • How feedback severity is interpreted and acted upon internally.
  • Whether feedback generation or processing can be configured or disabled depending on counterparty capabilities.
  • How property paths are generated and correlated with individual notices or notifications in a batch.
  • Which request-level and message-level failures are considered retryable.
  • How the implementation handles common retrieval cases, including no matching results, malformed values, unsupported filters, excessive reference counts, invalid date ranges, invalid cursors, authentication failures, authorization failures, unsupported API versions, and temporary service failures.

These decisions are important for interoperability, as not all counterparties may support sending feedback or processing received feedback in the same way.