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:
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, | ||
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, | 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, | 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, | Last free time | |
LFTCHANGED | Container visit Last Free Time has been changed | NZAKL, NZTRG, NZTIU | NZMKL, | New last free time | Old Last free time value |
LFTEXCEEDED | Container visit Last Free Time exceeded | NZAKL, NZTRG, NZTIU | NZMKL, | 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, | ||
LOPRELEASECANCELLED | Notice of Line Operator Release - cancelled | NZAKL, NZTRG, NZTIU, NZLYT | NZMKL, NZOLT, NZCHC, | ||
MPIRELEASE | Notice of MPI Release | NZAKL, NZTRG, NZTIU, NZLYT | NZMKL, NZOLT, NZCHC, | ||
MPIRELEASECANCELLED | Notice of MPI Release - cancelled | NZAKL, NZTRG, NZTIU, NZLYT | NZMKL, NZOLT, NZCHC, | ||
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 |
|
VesselETAChanged | Vessel ETA Changed |
|
VesselDeparture | Vessel Departure |
|
VesselETDChanged | Vessel ETD Changed |
|
ReceivalCommenceInlandChanged | Receival Commence Inland Changed |
|
ReceivalCutOffInlandChanged | Receival Cut Off Inland Changed |
|
ReceivalCommenceSeaportChanged | Receival Commence Seaport Changed |
|
ReceivalCutOffSeaportChanged | Receival Cut Off Seaport Changed |
|
VesselCancelled | Vessel Cancelled |
|
Subscription Create Response
...
We don’t provide any retries or error handling, please see below the response codes for troubleshooting.
HTTP response code | |
---|---|
| The request succeeded. The result meaning of "success" depends on the HTTP method. |
| The request succeeded, and a new resource was created as a result. This is typically the response sent after POST requests. |
| 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). |
| This response means "unauthenticated". That is, the client must authenticate itself to get the requested response. |
| 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. |
| The server cannot find the requested resource, likely due to incorrect container number or port code in the request. |
| 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
...