Page Comparison

...

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.

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

Subscription V2 Create Example

...

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

...

You can search for all active container event subscriptions for your API user by calling invoking a GET action on the subscriptions end point with no parameters:

Subscription V1 GET All Example

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

Subscription V1 GET All Response

The response payload lists all of you current subscriptions, for example:

...

[{
        "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"
        }
        ],
        "webhookURI": "https://enhct6aieo9t7.x.pipedream.net",
        "webhookToken": "123-456-789-000",
        "portCode": "NZAKL",
        "category": "IMPORT",
        "eventTypeCode": "CUSTOMSRELEASE",
        "facilityCode": ""
    },
    {
        "subscriptionId": 10,
        "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"
        }
        ],
        "webhookURI": "https://enhct6aieo9t7.x.pipedream.net",
        "webhookToken": "123-456-789-000",
        "portCode": "NZAKL",
        "category": "IMPORT",
        "eventTypeCode": "AVAILABLE",
        "facilityCode": ""
    }]

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:

...

Subscription V2 GET All Example

https://api.portconnect.io/v1v2/subscriptions/9

Subscription V2 GET All Response

The response payload lists the matching subscription, for example:

...

subscription V2 response returns an array of subscribed event type codes in the response.

[
    {
        "subscriptionId": 91395,
        "containers": [
            {
                "expirationDatetime": "20192022-0806-19T1111T17:0715:1958.883997+12:00",
                "subscriptionContainerId": 122590903,
                "containerNumber": "APHU6303593CAIU3549296",
                "userDefinedReference" : "User ref 1LFT ISO code test 2"
            },
            {
                "expirationDatetime": "20192022-0806-19T1111T17:0715:1958.883997+12:00",
                "subscriptionContainerId": 112590902,
                "containerNumber": "MEDU3085895OOLU1858222",
                "userDefinedReference" : "User ref 2LFT ISO code test 1"
            },
            {
                "expirationDatetime": "20192022-0806-19T1112T15:0745:1934.88399+12:00",
                "subscriptionContainerId": 132594031,
                "containerNumber": "MEDU5129708TCNU8050683",
				
                "userDefinedReference" : "UserAzure refTest 32"
            }
        ],
        "webhookURIeventTypeCodes": "https://enhct6aieo9t7.x.pipedream.net",[
           "webhookToken": "123-456-789-000AVAILABLE",
        "portCode":    "NZAKLCUSTOMSRELEASE",            
 "category": "IMPORT",         "eventTypeCode": "CUSTOMSRELEASEACTIVE",
            "facilityCodePRIORITYGATEIN":
""     }

Updating Subscriptions

A single subscription can be updated by sending a patch to the subscriptions end point, specifying the subscription id in the uri. 

Any containers supplied replace all existing containers in the subscription.

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:

Subscription Update

PATCH https://api.portconnect.io/v1/subscriptions/2 HTTP/1.1
Host: api.portconnect.io
Content-Type: application/json
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

{
"containers": [
    { "containerNumber": "CNIU2234429"},
    { "containerNumber": "CNIU2234430"},
    { "containerNumber": "CNIU2234431"},
    ],
  "webhookURI": "https://api.yourdomain.com/portconnect",
  "webhookToken": "secretsquirrel",
  "portCode": "NZAKL",
  "category": "IMPORT",
  "eventTypeCode": "AVAILABLE",
  "facilityCode": "   ],
        "category": "IMPORT",
        "facilityCode": "",
        "webhookURI": "https://enb8apr7yans.x.pipedream.net",
        "webhookToken": "123-456-789-000",
        "portCode": "NZTRG"
    },
    {
        "subscriptionId": 1397,
        "containers": [
            {
                "expirationDatetime": "2022-06-12T15:46:13.21+12:00",
                "subscriptionContainerId": 2594055,
                "containerNumber": "TCNU8050683",
                "userDefinedReference": "Azure Test 2"
            }
        ],
        "eventTypeCodes": [
            "BOOKINGDISCREPANCY",
            "GATEIN",
            "GATEOUT",
            "HAZARDGATERULE",
            "LOAD",
            "NOCEDO",
            "PINAVAILABLE",
            "PINSUSPENDED",
            "ACTIVE",
            "EXPORTCLEARED"
        ],
        "category": "EXPORT",
        "facilityCode": "",
        "webhookURI": "https://enb8apr7yans.x.pipedream.net",
        "webhookToken": "123-456-789-000",
        "portCode": "NZTRG"
    }
]

Searching for a Single Subscription

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

Subscription V1 Single GET Example

The following example returns the subscription details for subscription 9:

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

Subscription V1 Single GET Response

The response payload lists the matching subscription, for example:

Subscription Search

{
        "subscriptionId": 9,
        "containers": [
            {
                "expirationDatetime": "2019-08-19T11:07:19.883+12:00",
                "subscriptionContainerId": 12,
                "containerNumber": "APHU6303593",
                "userDefinedReference" : "User ref 1"
            },
            {
                "expirationDatetime": "2019-08-19T11:07:19.883+12:00",
                "subscriptionContainerId": 11,
                "containerNumber": "MEDU3085895",
                "userDefinedReference" : "User ref 2"
            },
            {
                "expirationDatetime": "2019-08-19T11:07:19.883+12:00",
                "subscriptionContainerId": 13,
                "containerNumber": "MEDU5129708",
				"userDefinedReference" : "User ref 3"
            }
        ],
        "webhookURI": "https://enhct6aieo9t7.x.pipedream.net",
        "webhookToken": "123-456-789-000",
        "portCode": "NZAKL",
        "category": "IMPORT",
        "eventTypeCode": "CUSTOMSRELEASE",
        "facilityCode": ""
    }

Subscription V2 Single GET Example

The following example returns the subscription details for subscription 1397:

https://api.portconnect.io/v2/subscriptions/1397

Subscription V2 Single GET Response

The response payload lists the matching subscription, for example:

{
        "subscriptionId": 1397,
        "containers": [
            {
                "expirationDatetime": "2022-06-12T15:46:13.21+12:00",
                "subscriptionContainerId": 2594055,
                "containerNumber": "TCNU8050683",
                "userDefinedReference": "Azure Test 2"
            }
        ],
        "eventTypeCodes": [
            "BOOKINGDISCREPANCY",
            "GATEIN",
            "GATEOUT",
            "HAZARDGATERULE",
            "LOAD",
            "NOCEDO",
            "PINAVAILABLE",
            "PINSUSPENDED",
            "ACTIVE",
            "EXPORTCLEARED"
        ],
        "category": "EXPORT",
        "facilityCode": "",
        "webhookURI": "https://enb8apr7yans.x.pipedream.net",
        "webhookToken": "123-456-789-000",
        "portCode": "NZTRG"
    }

Updating Subscriptions

A single subscription can be updated by sending a patch to the subscriptions end point, specifying the subscription id in the uri.  Any containers supplied replace all existing containers in the subscription.

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 35 can be updated to include containers:

Subscription V1 Update

PATCH https://api.portconnect.io/v1/subscriptions/35 HTTP/1.1

{
"containers": [
    { "containerNumber": "CNIU2234429"},
    { "containerNumber": "CNIU2234430"},
    { "containerNumber": "CNIU2234431"},
    ],
  "webhookURI": "https://api.yourdomain.com/portconnect",
  "webhookToken": "secretsquirrel",
  "portCode": "NZAKL",
  "category": "IMPORT",
  "eventTypeCode": "AVAILABLE",
  "facilityCode": ""
}

Subscription V2 Update

PATCH https://api.portconnect.io/v1/subscriptions/45 HTTP/1.1
{

    "containers": [
        {
            "expirationDatetime": "2022-06-12T15:46:13.21+12:00",
            "subscriptionContainerId": 2594055,
            "containerNumber": "TCNU8050684",
            "userDefinedReference": "Azure Test 2"
        }
    ],
    "eventTypeCodes": [
        "BOOKINGDISCREPANCY",
        "GATEIN",
        "GATEOUT",
        "HAZARDGATERULE",
        "LOAD",
        "NOCEDO",
        "PINAVAILABLE",
        "PINSUSPENDED",
        "ACTIVE"
    ],
    "category": "EXPORT",
    "facilityCode": "",
    "webhookURI": "https://enb8apr7yans.x.pipedream.net",
    "webhookToken": "123-456-789-000",
    "portCode": "NZTRG"
}

Response

A return code of 204 indicates the subscription has been updated successfully.

...

Subscriptions may be deleted by sending a delete request with an empty request body to the subscriptions end point, specifying the subscription to delete as a parameter in the URI.

Delete works the same for both versions of the subscription end point.

Example

Subscription Delete

DELETE https://api.portconnect.io/v1/subscriptions/334 HTTP/1.1

DELETE Hosthttps: //api.portconnect.io
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••/v2/subscriptions/497 HTTP/1.1

Response

A return code of 204 indicates the subscription has been deleted successfully.

...

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.

...

POST https://apitest.portconnect.io/v1/export-preadvices HTTP/1.1
Host: apitest.portconnect.io
Content-Type: application/json
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

{
  "header": {
    "shipperName": "ALNEMAH HALAL MEAT LIMITED",
    "bookingReference": "1AKL026740",
    "pointOfOriginCode": "Bay of Plenty",
    "loadPortFacility": "TCT",
    "vessel": {
      "lineOperatorCode": "HSUD",
      "shipName": "DEBUSSY",
      "voyageNumber": "138N",
      "partnerPortShippingReference": "USY138N",
      "loadPortCode": "NZTRG",
      "portOfDischarge": "USLGB",
      "foreignPortOfDischarge": "USLGB"
    },
    "notificationEmails": [
      "Cameron.Pitches@portconnect.co.nz"
    ],
    "userReference": "CAMTEST001"
  },
  "containers": [
    {
      "containerNumber": "CDPU3736837",
      "isoTypeCode": "2232",
      "flexiTank": false,
      "isFull": true,
      "commodityCode": "0201",
      "isNonOperatingReefer": false,
      "refrigeration": {
        "isFantainer": false,
        "requiredTemperature": -5.0,
        "refrigerationType": "Chilled"
      },
      "cargoWeightKg": 28000.0,
      "totalWeightKg": 30000.0,
      "containerSeals": [
        {
          "sealType": "Shipper",
          "sealCode": "555"
        }
      ],
      "arrivalCarrierType": "Truck"
    }
  ]
}

Response

A return code of 201 Created results when the export pre-advice request is submitted. Importantly, the response payload needs to be examined to determine if both the overall export pre-advice was created successfully, along with the associated container records.  For instance the above request will return success flags at the header and the container level:

...

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.

...

If the user reference is not found then a 404 Not Found response is returned.

Response

The response is the same format as the post request, with the addition of the status of the latest submission.  For example:

...

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.

DELETE https://apitest.portconnect.io/v1/export-preadvices HTTP/1.1
Host: apitest.portconnect.io
Content-Type: application/json
Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••

{
    "header": {
        "partnerPortCode": "NZTRG",
        "userReference": "POT_TEST1"
    },
    "containers": [
        {
            "containerNumber": "CONU1234560"
        }
    ]
}

Validation

Response

Success will result in a return code of 204 No Content.

...

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

Example

Storage pre-advice submit

...

At this time the only supported value for portCode is "NZAKL", and the only supported value for receiveLocation is "LNK"

Response

Success will result in a return code of 201 Created.

...

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"
			}
		}
	]
}

...

• partnerPortCode must be one of NZAKL, NZTRG, NZTIU or NZLYT

• vesselVisit must contain a minimum of vesselName and vesselVoyageNbr

• valid UN port codes must be used

• at least one booking item must be supplied

Response

Success will result in a return code of 201 Created.

...

A booking can be retrieved by sending a get request. 

Example

The following example retrieves the booking above:

...

https://api.portconnect.io/lines/v1/bookings/0AKL005396

Response

Success will result in a return code of 200 Ok.

...

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

Response

A return code of 204 indicates the subscription has been cancelled successfully.

...

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

...