Transport Operator Integration Guidelines

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. 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 (Shipping 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 (Shipping 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.

Pick-up Rights - Truck

Generate Pick-up Right - truck: assign driver

When your company is the (current) owner of the Release Right, you can assign a driver for the pick up of the container at the terminal. This driver needs to have a valid Alfapass.

The release information of the container (identification + Pick-up code) will be only send to the app when both Terminal and Commercial release are given. In case one of these two releases has not yet been given when assigning the pick up, the alfapass will be stored. At the moment the releases are okay, the container will be available for the driver.

When assigning a single driver to pick up a container, the driver’s Alfapass is used for identification. Therefore, the driver needs to have their personal active Alfapass. When an invalid Alfapass number is used when assigning the pick up, the pick-up will be cancelled and an error notification will be sent.

This call assigns a driver to the pick-up. Allows this driver to pick up the container at the terminal.

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.

Update Pick-up Right - truck

Combination of Revoking the previously assigned pick-up right + Create and assign to a new driver.

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 Pick-up Right - truck

Revokes the Pick-up Right from the current driver. Driver will not be able to pick up container.

In case you have already sent out the Pick up right to a driver and the container has not yet been picked up, you can revoke the right.

When you have sent out a Pick up Right, the forwarding of the Release Right is disabled. If you want to forward the Release Right to another party, you should revoke the Pick up Right first.

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.

Pick-up Rights - Barge / Rail

Generate Pick-up Right - barge / rail

When your company is the (current) owner of the Release Right, you can assign a pick-up of the container at the terminal for either barge or rail. A pick-up right will be generated for your company’s identity.

The release information of the container will be only send to the app when both Terminal and Commercial release are given. In case one of these two releases has not yet been given when assigning the pick up, the pick-up will be stored. At the moment the releases are okay, the container will be available for the barge or rail operator

This call assigns a pick-up for either barge or rail so that your company can pick-up the container at the terminal

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.

Update Pick-up Right - barge / rail

Combination of Revoking the previously assigned pick-up right + Create and assign a new pick-up

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. More info on notifications sent: Notifications for Transport Operators | Pick-up-Right-updated---barge-/-rail

Revoke Pick-up Right - barge / rail

Revokes the current Pick-up Right so that the container can’t be picked up with the registered means of transport.

When you have sent out a Pick up Right, the forwarding of the Release Right is disabled. If you want to forward the Release Right to another party, you should revoke the Pick up Right first.

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.

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.

	Field name	Type	Mandatory?	Allowed values	Field description
1	releaseIdentification	string	Yes	Free text	Unique release identification (per carrier).
2	billOfLadingNumbers	Array of strings	Yes	Free text	Bill of Lading number(s) of the container. The unique combination of container/BL will be used for the identification of the container release.
3	terminalCode	string	Yes	Terminal code provided to NxtPort during onboarding (for correct mapping)	The indicative terminal where the container will be available for pickup.
4	actionType	Enum	Yes	Different per action you need to perform. Check the specific action.	Action which is sent to the CPu platform, e.g. “Transfer”, “Accept“.
5	carrier> identificationType	Enum	No	“TIN” / “NxtEntityId” / “Eori” / “Duns” / “APCS”	Enter the type of identification of the carrier. Remark: TIN should be used for the VAT number of a company.
6	carrier> identificationCode	string	No	Free text	The value that belongs to the selected identification. Note that carrier is not mandatory, but if filled, a check will occur if the identificationCode is known
7	releaseTo> identificationType	Enum	Yes	“TIN” / “NxtEntityId” / “Eori” / “Duns” / “APCS”	Enter the type of identification of the party that will receive the Release Right. Remark: TIN should be used for the VAT number of a company.
8	releaseTo> identificationCode	string	Yes	Free text	The value that belongs to the selected identification.
9	releaseFrom> identificationType	Enum	Yes	“TIN” / “NxtEntityId” / “Eori” / “Duns” / “APCS”	Enter the type of identification of the party transfers the Release Right. Remark: TIN should be used for the VAT number of a company.
10	releaseFrom> identificationCode	string	Yes	Free text	The value that belongs to the selected identification.
11	equipmentNumber	string	Yes	Free text	The container number.
12	portLoCode	string	Yes	UN/LoCode	The UN/Locode of the operational port. For Antwerp this is BEANR.
13	reasonForAction	string	No	Free text	Free text to provide, is displayed in the audit trail of the Release Right.
14	pickupParty> partyType	Enum	Yes	“Truck” / “Barge“ / “Rail“	Mode of transport with which the container will be picked up As of 30 Nov 2022 , only Truck is supported. Other modes will follow shortly.
15	pickupParty> identificationType	Single value	Yes	“Alfapass“	Means of identification of the pick up party Only Alfapass is allowed.
16	pickupParty> identificationCode	string	Yes	Free text	The value that belongs to the selected identification.
17	meansOfTransport	string	Yes	Enum: [ use int value: 0 (Truck), use int value: 1 (Barge), use int value: 2 (Rail), use int value: 99 (Unknown) ]	Mode of transport with which the container will be picked up.

Notifications

As explained about the asynchronous handling within the CPu process, you - as a Transport Operator - 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 Transport Operators .

Need any further assistance?

Raise a support ticket on the NxtPort Support Portal