Info |
---|
This guide is intended for developers who want to integrate their own applications with PortConnect. |
...
Scheduled vessels: Returns scheduled vessel information, including expected time of arrival and departure.
Containers: Returns the latest detailed information for specified containers. Up to 10 containers can be searched at any one time.
Container event subscriptions: This is a suite of operations which allows container events to be sent to any end point you specify.
Export Pre-Advice: Submit export container details to our partner ports prior to gate-in.
Getting Started
...
Signing Up
...
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:
Code | Description | Supported Facility Codes | Event Value 1 | Event Value 2 |
---|---|---|---|---|
ACTIVE | Container record becomes live in PortConnect system | NZAKL, NZTRG, NZTIU, NZLYT | ||
AVAILABLE | Availability Advice (Container is fully released) | NZAKL, NZTRG, NZTIU, NZLYT | ||
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 | ||
CLEAREDCANCELLED | Cleared Advice cancelled | NZAKL, NZTRG, NZTIU, NZLYT | ||
CUSTOMSRELEASE | Notice of Customs Release | NZAKL, NZMKL, NZTRG, NZTIU, NZLYT, NZOLT | ||
CUSTOMSRELEASECANCELLED | Notice of Customs Release cancelled | NZAKL, NZMKL, NZTRG, NZTIU, NZLYT, NZOLT | ||
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, NZMKL, NZTRG, NZWII, NZTIU, NZOLT | Mode of transport, eg. Road | Identifier for the truck or train, eg. REL328 |
GATEOUT | Gate OUT Advice | NZAKL, NZMKL, NZTRG, NZWII, NZTIU, NZOLT, NZLYT, 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 | Last free time | |
LFTCHANGED | Container visit Last Free Time has been changed | NZAKL, NZTRG, NZTIU | New last free time | |
LFTEXCEEDED | Container visit Last Free Time exceeded | NZAKL, NZTRG, NZTIU | Last free time | |
LOAD | Notice of item loaded to Vessel | NZAKL, NZTRG, NZTIU, NZLYT | ||
LOPRELEASE | Notice of Line Operator Release | NZAKL, NZMKL, NZTRG, NZTIU, NZOLT, NZLYT, NZCHC | ||
LOPRELEASECANCELLED | Notice of Line Operator Release - cancelled | NZAKL, NZMKL, NZTRG, NZTIU, NZOLT, NZLYT, NZCHC | ||
MPIRELEASE | Notice of MPI Release | NZAKL, NZMKL, NZTRG, NZTIU, NZOLT, NZLYT, NZCHC | ||
MPIRELEASECANCELLED | Notice of MPI Release - cancelled | NZAKL, NZTRG, NZTIU, NZLYT | ||
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 |
...
Any errors in the request payload will result in a return code of 400 Bad request
. Further information will be supplied in the message payload.
...
Beta Endpoints
Vessel Schedule Notifications
Vessel Arrival
Vessel ETA Changed
Vessel Departure
Vessel ETD Changed
Receival Commence Changed
Receival Cut Off Changed
Vessel Cancelled
Subscription Create Example
Code Block | ||
---|---|---|
| ||
{
"vessels": [
{ "vesselRef": "KRJ3654"},
{ "lloydNumber": "9700524"},
{ "lloydNumber": "9188934"}
],
"webhookURI": "https://api.yourcompany.co.nz/webhooks/",
"webhookToken": "yoursecret",
"emailAddressList": ["info@portconnect.co.nz"],
"portCode": "NZTRG",
"wharfType": "Terminal"
} |
Subscription Create Response
Code Block | ||
---|---|---|
| ||
{
"subscriptionId": 36,
"vessels": [
{
"expirationDatetime": "2022-08-08T16:54:17.57+12:00",
"subscriptionVesselScheduleId": 73,
"vesselRef": "KRJ3654",
"lloydNumber": null,
"userDefinedReference": null
},
{
"expirationDatetime": "2022-08-08T16:54:17.57+12:00",
"subscriptionVesselScheduleId": 74,
"vesselRef": null,
"lloydNumber": 9700524,
"userDefinedReference": null
},
{
"expirationDatetime": "2022-08-08T16:54:17.57+12:00",
"subscriptionVesselScheduleId": 75,
"vesselRef": null,
"lloydNumber": 9188934,
"userDefinedReference": null
}
]
} |
Logic for Vessel Schedule Events
When PortConnect receive an update from the partner port, we will only generate another event if the previous raised event Arrival Dttm or Departure Dttm is different to the new file.
6 hour time limit for Notifications: E.g. It is currently 11.59am, Vessel ETD is set to 6pm so a Notification will be sent. If the time was 12.30pm a Notification would not be sent.
Notification Type |
|
Vessel Arrival |
|
Vessel ETA Changed |
|
Vessel Departure |
|
Vessel ETD Changed |
|
Receival Commence Inland Changed |
|
Receival Cut Off Inland Changed |
|
Receival Commence Seaport Changed |
|
Receival Cut Off Seaport Changed |
|
Vessel Cancelled |
|
...
Shipping Line Endpoints
PortConnect offers the following end points exclusively for the use of shipping lines. Shipping line developers will need to contact our user support team to have access to these endpoints. PortConnect associates an API user id with a specific line operator, so that storage pre-advice and booking api calls are associated with the correct shipping line. It isn't possible to send or retrieve information in relation to other shipping lines.
...
$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.
...