Hinterland Container Notification API Connection instructions

TARGET GROUP: Road, Barge and Rail operator

Introduction

This instruction serves to support the customer and the software supplier of the road, barge or rail operator, in quickly and efficiently realising a System Interface connection for the service Hinterland Container Notification (HCN). You read the following:

• Step-by-step implementation plan on this page
• HCN Tracking API on this page
• Querying supported terminal functionality on this page
• Use cases for the applicable modality road, barge or rail on the tabs above

The use cases include a description of the logical order in which the APIs must be called in order to realise these use cases. The Hinterland Container Notification APIs have been developed for a JSON payload. The API specification is available here. Two things to note:

• The API specification features APIs for all supported modalities (road, barge, rail).
• The API specification also features APIs that are used by the terminal only.

There are three relevant API categories for the operator in HCN: Operator APIs, Tracking APIs and Reference Data APIs. The Tracking API deserves some extra background explanation which has been covered in HCN Tracking API on this page.

Step-by-step implementation plan

Step	Explanation
You request the connection application form, fill it out and sign it and then return it to sales@portbase.com (only by the customer, not as a software supplier)	The application form is available at the services website. Select select ‘Subscribe to service'
You will receive your client ID and a client secret for the Hinterland Container Notification environments from Portbase Integration Services.	Your client ID and client secret will have to be included as key data in the API header for authentication and authorisation of the user.
You build and check the APIs based on this instruction and the API specification
You test the APIs in a test environment	Once the build has been completed, you test the message in a test environment. The environment that is used to realise the connection will be coordinated with you in collaboration with Portbase Integration services.
After successful testing, you will be connected to production by Portbase Integration services

HCN Tracking API

When you have submitted a container status request or pre-notification to the Terminal, in HCN you next listen to the response from the Terminal via a so-called Tracking API (also called listening API). This listening is a form of so-called long polling. We check whether the action of the terminal has actually resulted in a change in our system. You ‘see’ the result of this action or what has taken place in HCN in the listening API. The advantages of this listening API over a deprecated PUSH API (POST API in your system) or a standard short polling (GET API in our system) are:

• You do not realise an endpoint to have data delivered from the terminal. This is safer because there is no entry point on your end for break-ins.
• Let’s say that we deliver the data to you via PUSH API, but that this is unsuccessful. For example, because your endpoint is not reachable or it is reachable but the processing fails. In that scenario, HCN does not push the data again and the status update for your system is lost. This drawback is not applicable to the listening API.
• Regarding the processing, you will remain where you left off until you yourself indicate that the processing in your system has been successfully performed. You do this through a so-called Update position. You process the updates at your own pace. This for example allows you to schedule down time and synchronise your system with HCN at a later time.
• With this update position, you can even travel back in time and retroactively listen to updates. This allows you to trace and fix any errors in the processing and process the updates again so that your system displays the correct status.
• HCN sends the complete model. When Portbase adds a functionality, you will see this in the form of an addition to this model. You can ignore new features and have the flexibility to not listen to them until you need to. This means you are not bound by fixed API agreements. The HCN APIs will of course continue to be backwards compatible.

For the detailed operation of this tracking listening API see the API documentation here.

Querying supported terminal functionality

As a software supplier API developer you realise this use case by querying the terminal settings and based on these guide your Barge operator through the process steps which can differ per terminal

I WANT to know whether the terminal supports correcting a pre-notification or cancelling a pre-notification before I submit a status request.
SO THAT I do not perform any unnecessary work and know which terminal I need to inform outside of the system when the pre-notification needs to be corrected or cancelled.

and

I WANT to know which data I can or need to enter per type of operation for the container for each terminal before I submit a status request or pre-notification
SO THAT I do not perform unnecessary work and do not receive unnecessary error messages after I have submitted the pre-notification or status request

Note that the types of handlings per mode of transport are: full/unload, full/load, empty/unload and empty/load
Example: There are terminals that support the so-called ‘loading on size type’. In that case, an empty container that is to be loaded may be pre-notified under omission of the container number, stating the container size/type and, of course, the booking number. In that case, the container number is reported back by the Terminal via use case "Receiving information from the terminal" (the step on receiving loading/unloading confirmations).

Process steps	API operation
Step 1a. Request which process steps are supported per terminal	In case of the creation of the handling respectively visit inspect refdata/getTerminal In case of an update inspect the terminal settings that were applicable on the time of creation (of the handling respectively visit)
Step 1b. Request which data is relevant for each terminal	In case of the creation of the handling respectively visit inspect all terminalSettings which are listed per per type of handling (full/unloading, full/loading, empty/unloading and empty/loading) queried via refdata/getTerminal In case of an update inspect the terminal settings that were applicable on the time of creation (of the handling respectively visit)