Versions Compared

Old Version 89

changes.mady.by.user Chris Boxall

Saved on

compared with

New Version Current

changes.mady.by.user April Hickson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

This guide is intended for developers who want to integrate their own applications with PortConnect.

...

The PortConnect API endpoint to use from your client application is https://api.portconnect.io.  The developer portal can generate sample code in a number of different programming languages:

Image Modified

Image Modified

Image Modified

Feel free to use other API tools such as Postman.  See the resources section below for some Postman tests you can use.

...

In PortConnect terminology, a container visit refers to a container passing through a partner port.  The container visit might be an importImport, exportExport, transhipment Transhipment or a domestic Domestic supply chain movement.

Using the container visits search API, you can search for a single container or up to 10 containers in a single call. 

...

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


Event Types

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

Code

Description

Supported Port Codes

Supported Facility Codes

Event Value 1

Event Value 2

ACTIVE

Container record becomes live in PortConnect system

NZAKL, NZTRG, NZTIU, NZLYT

NZMKL, NZRUA



AVAILABLE

Availability Advice (Container is discharged and fully released)

NZAKL, NZTRG, NZTIU, NZLYT

NZMKL, NZRUA



AVAILABLECANCELLED

Availability Advice cancelled

NZAKL, NZTRG, NZTIU, NZLYT



BOOKINGDISCREPANCY

Discrepancy: Booking does not match Preadvise/Gate-in details

NZAKL, NZTRG, NZTIU, NZLYT

Container Visit value

Booking value

CLEARED

Cleared Advice (Container is fully cleared)

NZAKL, NZTRG, NZTIU, NZLYT



CEDORELEASE

CEDO Release

NZAKL, NZTRG, NZTIU, NZLYT

CEDOREVOKED

CEDO Revokes

NZAKL, NZTRG, NZTIU, NZLYT

CLEAREDCANCELLED

Cleared Advice cancelled

NZAKL, NZTRG, NZTIU, NZLYT



CUSTOMSRELEASE

Notice of Customs Release

NZAKL, NZTRG, NZTIU, NZLYT

NZMKL, NZOLT,
NZRUA



CUSTOMSRELEASECANCELLED

Notice of Customs Release cancelled

NZAKL, NZTRG, NZTIU, NZLYT



DEPART

Facility Departure Advice

NZAKL

NZWII



DISCHARGE

Discharge Advice

NZAKL, NZTRG, NZTIU, NZLYT



EXPORTCLEARED

CEDO is in place and there are no other stops

NZAKL, NZTRG, NZTIU, NZLYT



EXPORTCLEAREDCANCELLED

Export Cleared cancelled

NZAKL, NZTRG, NZTIU, NZLYT



GATEIN

Gate IN advice

NZAKL, NZTRG, NZTIU, NZLYT

NZMKL, NZWII, NZOLT, NZCHC,
NZRUA

Mode of transport, eg. Road

Identifier for the truck or train, eg. REL328

GATEOUT

Gate OUT Advice

NZAKL, NZTRG, NZTIU, NZLYT

NZMKL, NZWII, NZOLT, NZCHC,
NZRUA

Mode of transport, eg. Road

Identifier for the truck or train, eg. REL328

HAZARDGATERULE

Hazardous Cargo Gate-in rule applies

NZAKL, NZTRG, NZTIU, NZLYT



LFT24HOURS

Container visit Last Free Time within 24 hours

NZAKL, NZTRG, NZTIU

NZMKL,
NZRUA

Last free time

LFTCHANGED

Container visit Last Free Time has been changed

NZAKL, NZTRG, NZTIU

NZMKL,
NZRUA

New last free time

Old Last free time value

LFTEXCEEDED

Container visit Last Free Time exceeded

NZAKL, NZTRG, NZTIU

NZMKL,
NZRUA

Last free time


LOAD

Notice of item loaded to Vessel

NZAKL, NZTRG, NZTIU, NZLYT



LOPRELEASE

Notice of Line Operator Release

NZAKL, NZMKL, NZTRG, NZTIU, NZLYT

NZMKL, NZOLT, NZCHC,
NZRUA



LOPRELEASECANCELLED

Notice of Line Operator Release - cancelled

NZAKL, NZTRG, NZTIU,  NZLYT

NZMKL, NZOLT, NZCHC,
NZRUA



MPIRELEASE

Notice of MPI Release

NZAKL, NZTRG, NZTIU, NZLYT

NZMKL, NZOLT, NZCHC,
NZRUA



MPIRELEASECANCELLED

Notice of MPI Release - cancelled

NZAKL, NZTRG, NZTIU, NZLYT

NZMKL, NZOLT, NZCHC,
NZRUA



NOCEDO

No Cedo Warning

NZAKL, NZTRG, NZTIU, NZLYT

48, 24, 2 hour warning text


PINAVAILABLE

ExpressPin Available

NZAKL

Express Pin number


PINSUSPENDED

ExpressPin Suspended

NZAKL

Express Pin number


VESSELARRIVAL

Vessel Visit Actual Time of Arrival

NZAKL, NZTRG, NZTIU, NZLYT



VESSELDEPARTURE

Vessel Visit Actual Time of Departure

NZAKL, NZTRG, NZTIU, NZLYT



PRIORITYGATEIN

Automated Gate-In Notifications when containers arrive at Metroport with a status of Priority (Only available for Imports via Port of Tauranga).

NZTRG




Facility codes

  • NZMKL - MetroPort Auckland

  • NZCWF - Crawford Street, Hamilton

  • NZWII - Wiri, Ports of Auckland South Auckland Freight Hub

  • NZOLT - MetroPort Rolleston

  • NZCHC - CityDepot

  • NZRUA - Ruakura Freight Hub

...

Any or all of the following events may be sent in relation to a subscription.

Event Code

Event Description

Notes

VesselArrival

Vessel Arrival

  • No time limit for when the event can be sent.

  • Arrival date time is provided.

VesselETAChanged

Vessel ETA Changed

  • If the current time is more than 6 hours prior to the ETA changed time a Notification will be sent

  • Arrival Date has to be in the next 31 days.

  • The Notification will not be sent if the vessel has already arrived.

VesselDeparture

Vessel Departure

  • No time limit for when the event can be sent.

  • Departure date time is provided.

VesselETDChanged

Vessel ETD Changed

  • If the current time is more than 6 hours prior to the ETD changed time a Notification will be sent.

  • Arrival Date has to be in the next 31 days.

  • The Notification will not be sent if the vessel has already departed.

ReceivalCommenceInlandChanged

Receival Commence Inland Changed

  • If the current time is more than 6 hours prior to the ETA changed time a Notification will be sent

  • Arrival Date has to be in the next 31 days.

  • If the vessel has departed, no Notification will be sent.

ReceivalCutOffInlandChanged

Receival Cut Off Inland Changed

  • If the current time is more than 6 hours prior to the ETA changed time a Notification will be sent

  • Arrival Date has to be in the next 31 days.

  • If the vessel has departed, no Notification will be sent.

ReceivalCommenceSeaportChanged

Receival Commence Seaport Changed

  • If the current time is more than 6 hours prior to the ETA changed time a Notification will be sent

  • Arrival Date has to be in the next 31 days.

  • If the vessel has departed, no Notification will be sent.

ReceivalCutOffSeaportChanged

Receival Cut Off Seaport Changed

  • If the current time is more than 6 hours prior to the ETA changed time a Notification will be sent

  • Arrival Date has to be in the next 31 days.

  • If the vessel has departed, no Notification will be sent.

VesselCancelled

Vessel Cancelled

  • Inactive (when vessel visit isn't supplied by the partner port in vessel schedule file).

  • No time limit for when the event can be sent.

Subscription Create Response

...

We don’t provide any retries or error handling, please see below the response codes for troubleshooting.

HTTP response code

201 OK

The request succeeded. The result meaning of "success" depends on the HTTP method.

201 Created

The request succeeded, and a new resource was created as a result. This is typically the response sent after POST requests.

400 Bad request

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

401 Unauthorized

This response means "unauthenticated". That is, the client must authenticate itself to get the requested response.

403 Forbidden

The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource.

404 Not Found

The server cannot find the requested resource, likely due to incorrect container number or port code in the request.

500 Internal Server Error

The server has encountered a situation it does not know how to handle.

...

Resources

Postman

To assist with testing, we have created a set of Postman collections and an environment file, contained in PortConnectAPIPostmanTests20190510.zip

...