API Request Body

Header section

Level	Name	Required	Type	Description	Applicable Ports
0	header	PreadviceHeader	-	Pre-advice header information
1	shipperName	Mandatory	string	Shipper name	ALL
1	consigneeName	Optional	string	Consignee name	NZTRG / NZTIU
1	bookingReference	Mandatory	string	Booking reference	ALL
1	messageAction	Mandatory	string (Create/Cancel)	Message action type	ALL
1	pointOfOriginCode	Mandatory	string	Point of origin code	ALL
1	loadPortFacility	Mandatory	string	Load port facility	ALL
1	vessel	Mandatory	GenericPreadviceVessel	Vessel information	ALL
2	shipName	Conditional	string	Vessel Name	ALL
2	voyageNumber	Conditional	string	Voyage Number	ALL
2	partnerPortShippingReference	Conditional	string	Port Vessel reference	ALL
1	notificationEmails	Mandatory	string[]	List of notification email addresses	ALL
1	userName	Mandatory	string	User name	ALL
1	userReference	Mandatory	string	User reference	ALL
1	lineOperatorCode	Mandatory	string	Line operator code	ALL
1	loadPortCode	Mandatory	string	Load port code	ALL
1	portOfDischarge	Mandatory	string	Port of discharge	ALL
1	foreignPortOfDischarge	Optional	string	Foreign port of discharge	ALL
1	overseasDestinationFinal	Optional	string	Overseas destination final	ALL

Container section

Level	Name	Required	Repeats	Type	Description	Applicable Ports
0	containers	Mandatory	Yes	List of container information		ALL
1	containerNumber	Mandatory	No	string	Container number	ALL
1	attachedContainerNumbers	Optional	No	List<string>	List of attached container numbers	NZTRG / NZTIU
1	isoTypeCode	Mandatory	No	string	ISO type code for the container	ALL
1	flexiTank	Optional	No	bool	Indicates if the container is a flexi tank	NZTRG / NZTIU
1	isFull	Mandatory	No	bool	Indicates if the container is full	ALL
1	commodityCode	Mandatory	No	string	Commodity code	ALL
1	isNonOperatingReefer	Optional	No	bool	Indicates if the container is a non-operating reefer	ALL
1	refrigeration	Optional	No	GenericPreadviceRefrigeration	Refrigeration details for the container. Only required if container ISO Type is a Reefer ISO type	ALL
2	isFantainer	Optional	No	bool		ALL
2	co2Percent	Optional	No	float		ALL
2	o2Percent	Optional	No	float		ALL
2	humidityPercent	Optional	No	float		ALL
2	requiredTemperature	Conditional	No	float		ALL
2	refrigerationType	Optional	No	string	“Chilled”	ALL
2	offPowerTemperature	Optional	No	float		NZAKL
2	offPowerTimestamp	Optional	No	DateTime		NZAKL
2	onPowerTargetTime	Optional	No	DateTime		NZAKL
1	vent	Optional	No	GenericPreadviceVent	Vent details for the container	ALL
2	ventSettingType	Optional	No	string		ALL
2	ventSetting	Optional	No	float		ALL
1	cargoWeightKg	Mandatory	No	float	Cargo weight in kilograms	ALL
1	totalWeightKg	Mandatory	No	float	Total weight of the container in kilograms	ALL
1	hazardous	Optional	No	GenericPreadviceHazardous[]	List of hazardous details	ALL
2	hazardousClass	Conditional	Yes	float		ALL
2	unNumber	Conditional	Yes	string		ALL
2	packagingGroup	Conditional	Yes	string		ALL
2	limitedQuantities	Conditional	Yes	bool		ALL
2	marinePollutant	Conditional	Yes	bool		ALL
2	hazardousWeight	Conditional	Yes	float		ALL
2	quantity	Conditional	Yes	float		ALL
2	emsCode	Conditional	Yes	string		ALL
2	hazardContact	Conditional	Yes	string		ALL
3	name	Conditional	Yes	string		ALL
3	phone	Conditional	Yes	string		ALL
2	medicalFirstAidGuideSet	Conditional	Yes	string		NZTRG / NZTIU
2	flashPointSet	Conditional	Yes	float		NZTRG / NZTIU
1	overGauge	Optional	No	GenericPreadviceOverDimension[]	List of over-dimension details	ALL
2	area	Conditional	Yes	String	TOP, LEFT, RIGHT, FRONT, BACK	ALL
2	measureCm	Conditional	Yes	float		ALL
1	containerSeals	Mandatory	No	GenericPreadviceContainerSeal[]	List of container seals	ALL
2	sealType	Mandatory	Yes	string		ALL
2	sealCode	Mandatory	Yes	string		ALL
1	arrivalCarrierType	Mandatory	No	GenericPreadviceArrivalCarrierTypes?	Arrival carrier type	ALL
1	carrier	Mandatory	No	string	Carrier details	ALL
1	hazardousCertificateBase64	Optional	No	string	Base64 encoded hazardous certficate	NZTRG / NZTIU

Test URL:

POST https://apitest.portconnect.io/v1/export-preadvices

Example Messages

All fields example:

    {
	"header": {
		"shipperName": "FNT",
		"loadPortCode": "NZAKL",
		"bookingReference": "SHIPPINGLINEBOOKINGREF",
		"pointOfOriginCode": "AKC",
		"vessel": {
			"shipName": "CMA CGM SEMARANG",
			"voyageNumber": "2416",
			"partnerPortShippingReference": "CMC9741"
		},
		"loadPortFacility": "Auckland",
		"lineOperatorCode": "ARMC",
		"portOfDischarge": "AUMEL",
		"foreignPortOfDischarge": "AUMEL",
		"userReference": "UNIQUEREFERENCE",
		"notificationEmails": ["info@portconnect.co.nz"]
	},
	"containers": [{
		"containerNumber": "HAZD1234510"	
		"isoTypeCode": "4500",
		"isFull": true,
		"commodityCode": "74",
		"cargoWeightKg": 16000.0,
		"totalWeightKg": 18000.0,
		"hazardous": [{
			"medicalFirstAidGuideSet": true,
			"flashPointSet": true,
			"hazardousClass": "2.1",
			"unNumber": "1950",
			"packagingGroup": "1",
			"limitedQuantities": true,
			"marinePollutant": true,
			"hazardousWeight": 200.0,
			"quantity": "10",
			"emsCode": "F-BS-C",
			"hazardContact": {
				"name": "John Smith",
				"phone": "021 588 998"
			}
		},
		{
			"medicalFirstAidGuideSet": true,
			"flashPointSet": true,
			"hazardousClass": "2.2",
			"unNumber": "1950",
			"packagingGroup": "0",
			"limitedQuantities": false,
			"marinePollutant": false,
			"hazardousWeight": 1000.0,
			"quantity": "75",
			"emsCode": "F-YS-Y",
			"hazardContact": {
				"name": "John Smith",
				"phone": "021 588 998"
			}
		}],
		"containerSeals": [{
			"sealType": "Shipper",
			"sealCode": "4455"
		}],
		"arrivalCarrierType": "Rail",
		"carrier": "CONLIN"
	},
	{
		"containerNumber": "OOGC1234651"	
		"attachedContainerNumbers": [],
		"isoTypeCode": "22P1",
		"isFull": true,
		"commodityCode": "47",
		"isNonOperatingReefer": false,
		"cargoWeightKg": 16000.0,
		"totalWeightKg": 18000.0,
		"overGauge": [{
			"area": "Top",
			"measureCm": 10.0
		},
		{
			"area": "Left",
			"measureCm": 20.0
		},
		{
			"area": "Right",
			"measureCm": 30.0
		},
		{
			"area": "Front",
			"measureCm": 40.0
		},
		{
			"area": "Back",
			"measureCm": 50.0
		}],
		"containerSeals": [{
			"sealType": "Shipper",
			"sealCode": "TBC"
		}],
		"arrivalCarrierType": "Truck",
		"carrier": "AACAR "
	},
	{
		"containerNumber": "REEF1234510"		
		"isoTypeCode": "2230",
		"isFull": true,
		"commodityCode": "2199",
		"IsNonOperatingReefer": false,
		"refrigeration": {
			"isFantainer": false,
			"co2Percent": 50.0,
			"o2Percent": 40.0,
			"maximumOffPowerHours": 24.0,
			"offPowerTemperature": -21.0,
			"offPowerTimestamp": "2024-09-11T10:00:00+12:00",
			"onPowerTargetTime": "2024-09-11T10:00:00+12:00",
			"requiredTemperature": -21.0,
			"humidityPercent": 20.0,
			"refrigerationType": "Chilled"
		},
		"vent": {
			"ventSettingType": "PercentageOpen",
			"ventSetting": 30.0
		},
		"cargoWeightKg": 16000.0,
		"totalWeightKg": 18000.0,
		"containerSeals": [{
			"sealType": "Shipper",
			"sealCode": "1223"
		},
		{
			"sealType": "Shipper",
			"sealCode": "5665"
		}],
		"arrivalCarrierType": "Truck",
		"carrier": "WALTER"
	}]
}

Hazard example

{
	"header": {
		"shipperName": "FNT",
		"loadPortCode": "NZAKL",
		"bookingReference": "SHIPPINGLINEBOOKINGREF",
		"pointOfOriginCode": "AKC",
		"vessel": {
			"shipName": "CMA CGM SEMARANG",
			"voyageNumber": "2416",
			"partnerPortShippingReference": "CMC9741"
		},
		"loadPortFacility": "Auckland",
		"lineOperatorCode": "ARMC",
		"portOfDischarge": "AUMEL",
		"foreignPortOfDischarge": "AUMEL",
		"userReference": "UNIQUEREFERENCE",
		"notificationEmails": ["chris.boxall@portconnect.co.nz"]
	},
	"containers": [{
		"containerNumber": "REEF1234510",
		"isoTypeCode": "2230",
		"isFull": true,
		"commodityCode": "2199",
		"cargoWeightKg": 16000.0,
		"totalWeightKg": 18000.0,
		"hazardous": [{
			"medicalFirstAidGuideSet": true,
			"flashPointSet": true,
			"hazardousClass": "2.1",
			"unNumber": "1950",
			"packagingGroup": "1",
			"limitedQuantities": true,
			"marinePollutant": true,
			"hazardousWeight": 200.0,
			"quantity": "10",
			"emsCode": "F-BS-C",
			"hazardContact": {
				"name": "John Smith",
				"phone": "021 588 998"
			}
		},
		{
			"medicalFirstAidGuideSet": true,
			"flashPointSet": true,
			"hazardousClass": "2.2",
			"unNumber": "1950",
			"packagingGroup": "0",
			"limitedQuantities": false,
			"marinePollutant": false,
			"hazardousWeight": 1000.0,
			"quantity": "75",
			"emsCode": "F-YS-Y",
			"hazardContact": {
				"name": "John Smith",
				"phone": "021 588 998"
			}
		}],
		"containerSeals": [{
			"sealType": "Shipper",
			"sealCode": "1223"
		},
		{
			"sealType": "Shipper",
			"sealCode": "5665"
		}],
		"arrivalCarrierType": "Truck",
		"carrier": "WALTER"
	}]
}

Reefer example

{
	"header": {
		"shipperName": "FNT",
		"loadPortCode": "NZAKL",
		"bookingReference": "SHIPPINGLINEBOOKINGREF",
		"pointOfOriginCode": "AKC",
		"vessel": {
			"shipName": "CMA CGM SEMARANG",
			"voyageNumber": "2416",
			"partnerPortShippingReference": "CMC9741"
		},
		"loadPortFacility": "Auckland",
		"lineOperatorCode": "ARMC",
		"portOfDischarge": "AUMEL",
		"foreignPortOfDischarge": "AUMEL",
		"userReference": "UNIQUEREFERENCE",
		"notificationEmails": ["chris.boxall@portconnect.co.nz"]
	},
	"containers": [{
		"containerNumber": "REEF1234510",
		"isoTypeCode": "2230",
		"isFull": true,
		"commodityCode": "2199",
		"IsNonOperatingReefer": false,
		"refrigeration": {
			"isFantainer": false,
			"co2Percent": 50.0,
			"o2Percent": 40.0,
			"maximumOffPowerHours": 24.0,
			"offPowerTemperature": -21.0,
			"offPowerTimestamp": "2024-09-11T10:00:00+12:00",
			"onPowerTargetTime": "2024-09-11T10:00:00+12:00",
			"requiredTemperature": -21.0,
			"humidityPercent": 20.0,
			"refrigerationType": "Chilled"
		},
		"vent": {
			"ventSettingType": "PercentageOpen",
			"ventSetting": 30.0
		},
		"cargoWeightKg": 16000.0,
		"totalWeightKg": 18000.0,
		"containerSeals": [{
			"sealType": "Shipper",
			"sealCode": "1223"
		},
		{
			"sealType": "Shipper",
			"sealCode": "5665"
		}],
		"arrivalCarrierType": "Truck",
		"carrier": "WALTER"
	}]
}

Example Request Body short:

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

Example Response:

Export pre-advice success

{
    "success": true,
    "errors": [],
    "containers": [
        {
            "containerNumber": "CDPU3736837",
            "errors": [],
            "success": true
        }
    ]
}

However, should the requiredTemperature value be set to -50 in the example above, then the following is returned:

Export pre-advice partial failure

{
    "success": true,
    "errors": [],
    "containers": [
        {
            "containerNumber": "CDPU3736837",
            "errors": [
                "Temperature too high/low for the selected commodity (Range: -5.0 to 2.0). Change commodity or contact Terminal"
            ],
            "success": false
        }
    ]
}

Pre-Advice validation rules

Must provide a valid booking
Load Port must match the booking
Load Port must be valid
Line Operator code must be valid
Line Operator code must match the booking
Vessel Visit must match the booking
Discharge Port must match the booking
Reefer ISO type containers must have a Temperature (unless specified as a Non-Operating Reefer)
Freight Kind (Full vs Empty) must match the booking
Reefer temperatures must match the booking
Conditioning details must match the booking. Conditioning details include: Humidity %, Vent value, Vent Type, O2% and CO2%
Hazard UN Codes must match the booking
Container ISO Type Groups much match the booking.
Total Pre-Advised Containers must not exceed the booking quanta (count)
Seal Type must be valid

Submit Export Pre-advice

API Request Body

Header section

Container section

Test URL:

Example Messages

All fields example:

Hazard example

Reefer example

Example Request Body short:

Example Response:

Export pre-advice success

Export pre-advice partial failure

Pre-Advice validation rules