Release Party Integration Specifications

When an import container is commercially released, a Shipping Agent typically sends a PIN code to the Terminal and shares this code with the next party in the release chain (e.g. Forwarder, Transport Company, Beneficial Cargo Owner, …). This code, which is required to be granted access to the terminal and release the container, is distributed further in the supply chain until a party, which knows the PIN code, claims the container for pick up at the terminal.

By using the Certified Pick up (CPu) platform, a Shipping Agent will not create and distribute a PIN code to the Terminal, increasing the security of the release chain. Instead, the Shipping Agent sends the commercial release information towards the CPu platform, which vouches for a secure transfer of the “Release Right” until it is assigned to an entitled transporter to pick up the container at the terminal. The code to release the container will be sent via a secured and audited communication channel towards the Terminal.

Setting up your endpoint connection

To ensure our high security standards at NxtPort, we do not allow any anonymous API connection and we require of course a minimum set of security measures to be applied on any API connection. To that end, you will need to follow the steps below to set up the secure API connection with NxtPort.

You need to have completed the steps described on Getting Started with the API integration in order to proceed.

Asynchronous processing in CPu

To correctly integrate the set of API comprehended in the CPu application, it is important to be aware of the fact that CPu mainly works in an asynchronous fashion.

This means that you when making an API call, you will not get the result to your request in the response to your API call, but NxtPort will process your request and then send you a notification through the endpoint you have configured in the Getting Started process. To that end we advise you to pay quite close attention to the use of the Public Reference Id. This is the GUID you receive in the response of your API call.

This will allow you to keep track of the notifications in line with the request calls you have made.

When a API call returns a synchronous response, it is clearly marked in this guide.

Integration API calls

General remarks

Release Rights

Accept Release Right

Once another party (Ship Agent or another CPu Party) has transferred the Release Right of a container to your entity, you will receive a notification of type ReleaseRight and event Transferred. This will place the Release Right in a "queue", awaiting your acceptance or denial. It is not possible to transfer the Right of the container prior to either of these actions.

This action accepts the Release Right.

Response & notifications

This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.

Decline Release Right

Once another party (Ship Agent or another CPu Party) has transferred the Release Right of a container to your entity, you will receive a notification of type ReleaseRight and event Transferred. This will place the Release Right in a "queue", awaiting your acceptance or denial. It is not possible to transfer the Right of the container prior to either of these actions.

This action declines the Release Right and returns it to the sender.

Response & notifications

This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.

Transfer Release Right

In case you received and accepted a Release Right from a previous party (can be either the original Ship Agent or another Party in the supply chain), you can transfer the right to the next party in the chain.

This call allows you to transfer a Release Right to another stakeholder. As soon as the other stakeholder accepts the Right, they will hold & be able to manage the Right themselves.

When transferring a container, the transferring party is required to provide detailed information about the Release Right which he received in the previous steps. We verify if the provided information matches with the information that we have received from the original source and send via notifications to the Right owners, increasing the security about Release Right transfers.

Response & notifications

This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.

Revoke Release Right

This call allows you to revoke a Release Right which you previously transferred to another stakeholder. The Release Right will return to your company. The other stakeholder won’t be able to transfer the Right or pick up the container anymore.

Since release 3.1.0 a release right can be revoked as well if it has been accepted by the next entity or another entity down the chain.

Response & notifications

This is an asynchronous call; you will get a direct API response containing a public reference id and a notification containing the relevant information on your channel.

Get list of Release Rights assigned to my company

This will trigger you to receive a notification on your predefined notification channel. Within you will receive the details of all Release Rights currently assigned to your company with their corresponding Green Lights.

Generic Services

Get Release Detail

At any time, stakeholders that are allowed to see the information, can retrieve the detail and greenlights of a specific container release.

This will trigger you to receive a notification on your predefined notification channel. Within you will receive the detail of the container with its corresponding Green Lights.

Company Registry

This a synchronous call available to all CPu parties, which allows for querying the NxtPort register for other existing CPu parties and their respective identification values.

At any time, stakeholders that are allowed to see the information, can retrieve the details of any CPu connected party.

Synchronous Responses

{
  "searchFilter": {
    "eori": "string",
    "duns": "string",
    "vat": "string",
    "nxtEntityId": "string"
    "entityName": "string",
    "apcsCode": "string",
    "page": 1,
    "pageSize": 25
  },
  "phoneBookItems": [
    {
      "apcsCode": "string",
      "addresses": [
        {
          "addressTypeCode": "string",
          "street": "string",
          "postalCode": "string",
          "city": "string",
          "country": "string",
          "contactName": "string",
          "contactEmail": "string"
        }
      ],
      "nxtEntityId": "string",
      "name": "string",
      "vat": "string",
      "duns": "string",
      "eori": "string",
      "scac": "string",
      "apcs": "string",
      "externalId": "string"
    }
  ],
  "totalRows": 0,
  "totalPages": 0,
  "publicReferenceId": "string",
  "externalReferenceId": "string"
}

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-1fa221c60594f6428678fd0fe54140a8-d1aecb5a9485b64d-00",
    "errors": {
        "Page": [
            "'Page' must be greater than or equal to '1'."
        ]
    }
}

{
  "type": "string",
  "title": "string",
  "status": 401,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}

{
  "type": "string",
  "title": "string",
  "status": 405,
  "detail": "string",
  "instance": "string",
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}

Notification Service

This API call allows you to retrieve notifications sent to your company.

Notifications can be retrieved up to 168 hours in the past from the time of your request (e.g. on 08 April at 13h00 you can retrieve all notifications dating from 01 April 13h00 onwards).

The timeWindowFrom and timeWindowTo query parameters will be available starting from version 3.11.0 of the API.

Responses

[
  {
    "nxtEntityId": "string",
    "equipmentNumber": "string",
    "publicReferenceId": "string",
    "releaseId": "string",
    "externalReferenceId": "string",
    "storedOn": "ISO_Timestamp",
    "message": "string",
    "type": "string",
    "event": "string"
  }
  // object repeated for all notifications
]

{
    "statusCode": 401,
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

// empty object

{
    "identifier": "2304c375-30e2-408b-ac74-4c1b67ceaabf",
    "error": "An unexpected error has occured, please try again later. If the problem persists, please contact NxtPort Support.",
    "extraInfo": null
}

Additional information

Direct API responses to asynchronous calls

This overview contains the direct responses you might receive to the asynchronous calls.

{
  "publicReferenceId": "GUID",
  "externalReferenceId": "string"
}

{
  "publicReferenceId": "GUID",
  "externalReferenceId": "string"
}

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-a5601c96c250de464a5305102370cc7e-011ec98b63cf25c4-00",
    "errors": {
        "PortLoCode": [
            "'Port Lo Code' must not be empty.",
            "'Port Lo Code' must be equal to 'BEANR'."
        ],
        "EquipmentNumber": [
            "'Equipment Number' must not be empty."
        ]
    }
}

Request body fields

Below you can find the overview of all the request body field keys which are used in the API calls.

This overview acts like a reference guide, not all fields are to be included in each call. The request bodies are always marked with the calls.

Notifications

As explained about the asynchronous handling within the CPu process, you - as a Release Party - will receive various notifications.

Some of these will be asynchronous responses to calls you have submitted, some will be notifications triggered by actions performed by other parties in the release process.

You will find detailed information tailored to your role in CPu on Notifications for Release Parties .

Need any further assistance?

Raise a support ticket on the NxtPort Support Portal