Terminal Operator Integration Guidelines

While all parties involved in the container import flow will be prompted to give release information, only two parties are considered to be “data providers”. These entities, being Shipping Agents and Terminal Operators, need to give their approval before a container can be picked up.

To participate in CPu as a Terminal Operator, you will need to follow the steps described below:

• register and subscribe to Certified Pick up. You can find more information on this in the Getting Started with the API integration guide

• Testing must be performed on User Acceptance Environment before moving to production

CPu requires you to provide the following actions / functions / transactions:

• Discharge of a container (COARRI Discharge)

• Gate in and Gate Out movements of the containers (CODECO messages)

• Terminal Release confirmation

Please note that with CPu, the final responsibility to let a container leave the terminal will remain with the Terminal Operator.

The Terminal Operator can always overrule CPu and decide to release a blocked container.

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

It is your responsibility to inform NxtPort in advance about which message type you’re using, as it requires a different setup on our end. You should have provided us this info during your onboarding as described on the Getting started with the API integration guide.

Integrating using EDIFACT messages

We strongly encourage you to integrate the CPu API with JSON messages instead of EDIFACT. If you wish to set up a connection with COARRI & CODECO messages, please contact support.

General remarks

Release Lights

Submit Terminal Release

The Terminal Release cannot be sent to NxtPort through EDI messages. These can only be sent in either by API call or by using the User Interface.

Releases the container from the terminal yard, indicating that the container is ready to be picked up.

Will set the Terminal Release light to GREEN.

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.

A successful request will generate a notification of type ReleaseLight with action terminalRelease that will be sent to

• Your own notification channel and

• Towards the Shipping agent

• Towards the Release Right owner

To get the current state of a container, please refer to to the Get Release Detail section of this document.

Block Terminal Release

For as long as the container is not yet picked up, the terminal is able to block the container on the terminal. The container will still be present in the CPu backbone, but no Pick up right can be generated.

Will set the Terminal Release Light to RED.

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.

The endpoint for the update of the terminal release is identical to the one that is used when submitting a terminal release. Therefore, the responses will also be the same.

A successful request will generate a notification of type ReleaseLight with action terminalBlocked that will be sent to

• Your own notification channel

• Towards the Shipping agent

• Towards the Release Right owner

Submit Terminal Discharge

Will set the Terminal Discharge light to GREEN, indicating either:

• the container has been discharged from the vessel

• the container has arrived on the terminal from another terminal (shift)

The old ingestion URL https://ingestion.nxtport.com/ingestion/{{your_ingestion_id}} is still active, but will be disabled in the future. You will be informed well in advance when this happens.

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.

Submit Terminal Gate Out

This action allows the terminal to register a gate out operation event for a container.

Will put the terminal gate out light to GREEN.

A Gate Out will FINALIZE the release and archive the container in the CPU system.

NOTE: NxtPort will process the Gate Out message as the FINAL step in the CPu process. Once the Gate Out is received, this will mark the container as being finalized and will “archive” it.

This means that if you have sent in a Gate Out for a container, this container will no longer be visible in the UI. This is also applicable in case the Gate Out message is received before any other transactions is received, meaning that for those containers where a Gate Out is received before a commercial release, there will be NO visibility on that release in CPu.

The old ingestion URL https://ingestion.nxtport.com/ingestion/{{your_ingestion_id}} is still active, but will be disabled in the future. You will be informed well in advance when this happens.

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 Right Validation

Asynchronous Pick-up validation

At any time, stakeholders that are allowed to see the information, can verify if an identification code (eg alfapass number) is allowed to pick-up a container. The response is sent in an asynchronous notification.

Using this call, you as a Terminal Operator can verify the status of any container and check if it can be picked 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.

Synchronous Pick-up validation

At any time, stakeholders that are allowed to see the information, can verify if an identification code (eg alfapass number) is allowed to pick-up a container. In this method, the requested information is returned in a synchronous response.

Using this call, you as a Terminal Operator can verify the status of any container and check if it can be picked up.

Response & notifications

This is an synchronous call, you will get a direct API response:

{
    "alfapassNumber": "{{provided_alfapass_number}}",
    "releaseIdentification": [
        {
            "isValid": true,
            "errorMessages": null,
            "status": "RELEASED",
            "greenLights": [
                {
                    "greenLightName": "CommercialRelease",
                    "greenLightValue": "OK",
                    "greenLightColor": "Green"
                },
                {
                    "greenLightName": "TerminalOperation",
                    "greenLightValue": "DISCHARGED",
                    "greenLightColor": "Green"
                },
                {
                    "greenLightName": "TerminalReady",
                    "greenLightValue": "RELEASED",
                    "greenLightColor": "Green"
                },
                {
                    "greenLightName": "Customs",
                    "greenLightValue": "RELEASED",
                    "greenLightColor": "Green"
                },
                {
                    "greenLightName": "GateOperation",
                    "greenLightValue": "UNKNOWN",
                    "greenLightColor": "Gray"
                },
                {
                    "greenLightName": "PickupLight",
                    "greenLightValue": "ASSIGNED",
                    "greenLightColor": "Green"
                }
            ],
            "equipmentNumber": "{{equipment_number}}",
            "billOfLadingNumbers": [
                "{{bl_number}}",
                "{{bl_number}}"
            ]
        }
    ]
}

{
    "alfapassNumber": "{{provided_alfapass_number}}",
    "releaseIdentification": [
        {
            "isValid": false,
            "errorMessages": null,
            "status": "BLOCKED",
            "greenLights": [
                {
                    "greenLightName": "CommercialRelease",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "TerminalOperation",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "TerminalReady",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "Customs",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "GateOperation",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                },
                {
                    "greenLightName": "PickupLight",
                    "greenLightValue": "<see Green Light table>",
                    "greenLightColor": "<see Green Light table>"
                }
            ],
            "equipmentNumber": "{{equipment_number}}",
            "billOfLadingNumbers": [
                "{{bl_number}}",
                "{{bl_number}}"
            ]
        }
    ]
}

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

Validate Alfapass

This a synchronous call available to all CPu parties to verify if a provided Alfapass is valid or not.

The response will be a Boolean true or false.

Response & notifications

The synchronous response will be a Boolean true or false.

Validate Truck Release Right

Synchronous call

Validate if the queried Transport Operator holds the Release Right.

UPDATED with CPu version 2.19.0:

• portLoCode no longer mandatory in request body

• releaseIdentification object replaced by equipmentNumber field -> releaseIdentification>billOfLadingNumbers & releaseIdentification>releaseIdentification no longer applicable

• new possibilities for synchronous responses (added to table)

• If both ownerNxtEntityId & alfapassNumber (when provided) are invalid or unknown, the body errorMessages array will return multiple messages, detailing the relevant errors.

• The queried company ownerNxtEntityId must have the role of Transport Operator.

Response & notifications

This is an synchronous call, you will get a direct API response:

{
    "isValid: true,
    "errorMessages": []
}

{
    "isValid: false,
    "errorMessages": [
        "Alfapass validation error: Invalid alfapass",
        "Alfapass validation error: Unknown alfapass"
    ]
}

{
    "isValid": false,
    "errorMessages": [
        "Entity not found"
    ]
}

{
    "isValid": false,
    "errorMessages": [      
        "Release not found"
    ]
}

{
    "isValid": false,
    "errorMessages": [
        "Release is assigned to a different terminal"
    ]
}

{
    "isValid": false,
    "errorMessages": [
        "Multiple release rights found",
        "Entity not found"
    ]
}

{
    "isValid": false,
    "errorMessages": [
        "Multiple release rights found"
    ]
}

{
    "isValid": false,
    "errorMessages": [   
        "No release rights found within respected time window of 14 days"
    ]
}

{
    "isValid": false,
    "errorMessages": [
        "Multiple release rights found",
        "No release rights found within respected time window of 14 days"
    ]
}

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "GUID",
    "errors": {
        "OwnerNxtEntityId": [
            "'Owner Nxt Entity Id' must not be empty."
        ]
    }
}

{
    "identifier": "GUID",
    "error": "An unexpected error has occured, please try again later. If the problem persists, please contact NxtPort Support.",
    "extraInfo": null
}

Get Release Right detail as Terminal Operator

This API call will be made available with version 2.25. Keep an eye on https://documentation.nxtport.com/certified-pickup/release-notes or our Statuspage for when this release is expected.

This API call enables you to retrieve the details (including the Transport Operator identifiers, means of transport & Alfapass) of a Release Right of a container linked to your terminal.

Synchronous responses

{
  "releaseId": "string",
  "equipmentNumber": "string",
  "releaseIdentification": "string",
  "billOfLadingNumbers": [
    "string"
  ],
  "releaseOrderReference": "string",
  "emptyReturnReference": "string",
  "terminalName": "string",
  "terminalCode": "string",
  "portLoCode": "string",
  "lights": {
    "greenLightName": "string",
    "greenLightValue": "string",
    "color": "string",
    "dateLastUpdated": "{{ISO_timestamp}}"
  },
  "releaseDateTimeUtc": "{{ISO_timestamp}}",
  "expirationDateTimeUtc": "{{ISO_timestamp}}",
  "shippingAgentName": "string",
  "encryptedAlfapassNumber": "string",
  "transportOperator": {
    "nxtEntityId": "string",
    "name": "string",
    "eori": "string",
    "tin": "string",
    "apcs": "string",
    "duns": "string"
  },
  "meansOfTransport": "Truck"
}

Encryption of Alfapass number

In order to maximize security, the Alfapass number in the response body of the above call is encrypted.

In order for CPu to encrypt this, we will need to know your public key. You can share your public key using following call. The received public XML key will be stored in our database as a compressed string.

1. Generate a public and private RSA key pair

You can generate a key pair using attached executable.

SHA256 checksum: BD2E63F0E10E1A3395ABFE5D72B12F54C943BF552F62E37B034B342006F45D94

ConsoleRsaKey.runtimeconfig.zip

• Download & unzip the zip file

• Open the .exe file using a command prompt

Example output:

The executable uses following codebase:

using System.Security.Cryptography;
string publicKey;
string privateKey;
using (var rsa = new RSACryptoServiceProvider())
{
    // Get the public and private keys
    publicKey = rsa.ToXmlString(false);
    privateKey = rsa.ToXmlString(true);
}

Console.WriteLine("PRIVATE");
Console.WriteLine(privateKey);

Console.WriteLine("-----");
Console.WriteLine("PUBLIC");
Console.WriteLine(publicKey);

2. Submit the public key to NxtPort using the provided authenticated API

Important: it is your responsibility to maintain the corresponding private key at your end to decrypt the Alfapass number. If you lose this, you will need to submit a new public key to the CPu platform. All previously encrypted data will be rendered unusable if a new public key is received.

Response

200 - OK

{
  "errors": [
    "string" // empty if all ok
  ],
  "terminalNxtEntityId": "{{your_nxtport_id}}",
  "publicKey": "{{your_compressed_public_key}}"
}

3. Use the private RSA key to decrypt the Alfapass number returned by the get Release Right Detail API

This needs to be implemented at your end, you can decrypt the Alfapass with the generated private key.

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 greenlights.

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",
    "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"
    }
  ],
  "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 1.0 (deprecated)

This version of the notification service will be retired with CPu release 2.25 . Please use version 2.0 (see below).

This API call allows you to retrieve the notification(s) sent to your notification channel by CPu. You will need either the equipment number OR the Public Reference ID OR the External Reference ID. Values can be combined.

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).

Response & notifications

This is an synchronous call, you will get a direct API response:

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

[
  // empty array
]

{
    "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
}

Notification Service 2.0

This API call will be made available with CPu release 2.25. Check Release notes or our statuspage for when this release is expected.

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).

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."
        ]
    }
}

Notifications

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

Need any further assistance?

Raise a support ticket on the NxtPort Support Portal