Page Comparison

...

Use container event subscriptions, or "subscriptions", when you want PortConnect to send you an http (“webhook”) callback when a particular container event occurs.  This is an alternative to the email / xml based notifications which are also operated by PortConnect.

Creating a Subscription

To receive callbacks for particular container events, you need to create a subscription by posting to a request the subscriptions endpoint.   Each . Version 1 requests a single container visit event type code per request, Version 2 supports multiple container visit event type codes in a single request. Version 2 also supports the use of “ALL” to subscribe to all events for one or more containers.

Version 1

Each subscription relates to a single event type, however multiple containers can be included. 

For version 1, a new subscription is created for every unique combination of PortCode, Category, EventTypeCode and FacilityCode .  If a subscription already exists for a particular combination, then containers are added to that subscription.

Subscription V1 Create Example

For example, the following subscription request will result in a webhook callback when any of the three specified import containers become available:

Subscription Create Example

POST https://api.portconnect.io/v1/subscriptions HTTP/1.1

Host: api.portconnect.io
Content-Type: application/json
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

{
  {
  "containers": [
    { "containerNumber": "MEDU3085895", "userDefinedReference" : "User ref 1"},
    { "containerNumber": "APHU6303593", "userDefinedReference" : "User ref 2"},
    { "containerNumber": "MEDU5129708", "userDefinedReference" : "User ref 3"}
  ],
  "webhookURI": "https://api.yourcompany.co.nz/webhooks/portconnect/webhooks/portconnect",
  "webhookToken": "yoursecret",
  "portCode": "NZTRG",
  "category": "IMPORT",
  "eventTypeCode": "AVAILABLE",
  "facilityCode": null
}

Version 2

Version 2 of the subscription API supports multiple container event types, as well as the of “ALL” to subscribe to all possible events. Event type codes are supplied as an array.

Subscription V2 Create Example

POST https://api.portcon2nect.io/v2/subscriptions HTTP/1.1

{
  "portCode": "NZTRG",
  "category": "IMPORT",
  "eventTypeCodes": ["DISCHARGE", "AVAILABLE"],
  "webhookURI": "https://enb8apr7yans.x.pipedream.net",
  "webhookToken": "yoursecret123-456-789-000",
  "portCodefacilityCode": "NZTRG"null,
  "containers": [{"categorycontainerNumber": "IMPORTTCNU8050683",
  "eventTypeCodeuserDefinedReference" : "AVAILABLE",Azure Test 2"}  
 "facilityCode": null]
}

Request Validation Rules

You must specify the uri location where you want the webhook callback to be sent, and optionally a token that you can use to verify the call. A new subscription is created for every unique combination of PortCode, Category, EventTypeCode and FacilityCode .  If a subscription already exists for a particular combination, then containers are added to that subscription.Other rules common to both versions are:

• Valid port codes are: NZAKL, NZTRG, NZTIU or NZLYT

• Valid category codes are: IMPORT, EXPORT, TRANSHIPMENT, DOMESTIC

• Facility codes are optional and relate to the port facility where the event takes place. If no facility code is specified, then webhook callbacks will be sent whenever the event occurs, regardless of the location.  For instance, if a subscription is created for an export "gate in", and the container is gated in to both an inland port and the sea port, then two gate in events will be sent as webhook callbacks.

• Only some event type codes support the use of the facility code, in all other cases a null value should be supplied.  Refer to the table below.

User Defined References

• We only permit one userDefinedReference per container. This is a maximum of 50 characters and designed to support container visit identifiers in calling systems.

• The user defined reference will be included in the webhook callback payload against the specified container.

• If you create a new subscription with a different user defined reference, it will overwrite the existing subscription including the user defined reference.

• If you have already received events against the first subscription you will receive future events against the new subscription with the new user defined reference.

Notification Types

Valid event type codes are shown in the following table, along with event values that are returned in the webhook callback payload:

...

Success will result in a return code of 201 Created. The response to the request will confirm the containers in the subscription details. 

Subscription Create Response (V1 and V2)

{
    "subscriptionId": 9,
    "containers": [
        {
            "expirationDatetime": "2019-08-19T10:51:29.163+12:00",
            "subscriptionContainerId": 12,
            "containerNumber": "APHU6303593",
            "userDefinedReference" : "User ref 1"
        },
        {
            "expirationDatetime": "2019-08-19T10:51:29.163+12:00",
            "subscriptionContainerId": 11,
            "containerNumber": "MEDU3085895",
            "userDefinedReference" : "User ref 2"
        },
        {
            "expirationDatetime": "2019-08-19T10:51:29.163+12:00",
            "subscriptionContainerId": 13,
            "containerNumber": "MEDU5129708",
            "userDefinedReference" : "User ref 3"
        }
    ]
}

...

For testing purposes, you may find it useful to create a webhook uri using Request Bin or similar.  This allows you to easily view the webhook payload.

Example

Multiple events may be returned in a single payload, as in this example:

...

You can search for all active container event subscriptions for your API user by calling the subscriptions end point:

Example

https://api.portconnect.io/v1/subscriptions

...

Searching for a Single Subscription

...

If you know the subscription id, you can search for the details of a single subscription:

Example

The following example returns the subscription details for subscription 9:

...

The response payload lists all of you current subscriptionsthe matching subscription, for example:

Subscription Search

...

You can update the port code, category, event type and facility codes if you wish, but this isn't recommended as a different subscription id can result, possibly causing confusion.

Example

For instance, subscription id w can be updated to include containers:

...

Subscriptions may be deleted by sending a delete request with an empty request body to the subscriptions end point.

Example

Subscription Delete

DELETE https://api.portconnect.io/v1/subscriptions/3 HTTP/1.1
Host: api.portconnect.io
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

...

In order to understand the Export Pre-advice submission, some familiarity with the Export Pre-advice User Guide is recommended. This details how export pre-advice submitted via the PortConnect website. The structure of the API is conceptually very similar to this screen, comprising a header with a list of containers being submitted.

Example

This is a basic example of an export pre-advice message comprising the header with a single container record.  Additional properties allow the submission of refrigeration, vent, hazardous and over gauge settings, and these are detailed in the developer test portal.

...

An export pre-advice can be retrieved using a GET to the export-preadvices end point, specifying the port and user reference in the URL,  and optionally a container number.  Specifying the container number restricts the response to only the export pre-advice header and the container number.

Example

The following example returns all information relating to the export pre-advice submitted above.

...

This operation cancels one or more containers in an export pre-advice. The export pre-advice is identified through the combination of a partner port code and a user reference.

Example

Containers to be cancelled from an export pre-advice are specified in the request payload of the delete action, as in this example.

...

A storage pre-advice can be submitted by posting to the lines/storage-pre-advices endpoint.

Example

Storage pre-advice submit

...

A booking consists of top level booking information and one or more booking items.   Each booking item can optionally have hazardous and conditioning information. 

Example

Submit a Booking

POST https://api.portconnect.io/lines/v1/bookings HTTP/1.1
Host: api.portconnect.io
Content-Type: application/json
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••
{
	"bookingNbr": "0AKL005396",
	"partnerPortCode": "NZTRG",
	"vesselVisit": {
		"vesselName": "BROTONNE BRIDGE",
		"vesselIMO": "9486116",
		"vesselCallSign": "",
		"vesselVoyageNbr": "010N",
		"vesselReference": "ROT010N"
	},
	"msgReferenceNbr": "132576",
	"shipperName": "BOLLORE LOGISTICS NEW ZEALAND LTD",
	"consigneeName": "",
	"loadPortCode": "NZTRG",
	"dischargePortCode": "PFPPT",
	"finalDestinationPortCode": "PFPPT",
	"originPortCode": null,
	"bookingCategoryCode": "Export",
	"items": [{
			"isoTypeCode": "2232",
			"quantity": 1.0,
			"bookingStatus": "FCL",
			"grossWeightKg": 14148.0,
			"commodityDesc": "FOOD:(NOS,CHILLED)",
			"temperatureRequired": 2.0,
			"oversizeFrontCm": null,
			"oversizeBackCm": null,
			"oversizeLeftCm": null,
			"oversizeRightCm": null,
			"oversizeTopCm": null,
			"hazards": [{
					"unHazardNumber": "1950",
					"imdgClass": "2.2"
				}
			],
			"conditioning": {
				"cO2Required": null,
				"o2Required": null,
				"humidityRequired": null,
				"ventRequired": 25.0,
				"ventRequiredUnit": "FlowM3PerHour"
			}
		}
	]
}

...

A booking can be retrieved by sending a get request. 

Example

The following example retrieves the booking above:

...

A booking can be cancelled in the PortConnect system by sending a delete request with an empty request body to the bookings end point, specifying the booking you want to delete.

Example

Cancel a Booking

DELETE  https://apitest.portconnect.co.nz/v1/bookings/0AKL005396/HSUD

...

• $0.05NZD per call if not subscribed to Track & Trace

• Free for Subscribed Track & Trace users

Container Visits

• $0.05NZD per container/per call (max 10 containers per call) when searching containers directly.

Container Event Subscriptions

• $0.20NZD per event update (Notification) sent*

• Includes 1 free callback to the container visit URL to retrieve standing container data (provided in the callback payload).

*High volume users may qualify for preferred customer discounts.

...