Booking Endpoint Overview

Field

Required?

Data Type

Description

bookingSource

optional

string

Identifies the channel by which the booking was received, for example, email, phone, EDI.

bookingReference

mandatory

string

A customer supplied reference that uniquely identifies this booking request.

bookingType

optional

string

The type of booking to be created, that is, standard.

bookerCode

optional

string

The Customer Address Code for the party requesting the booking.

freightPayerCode

mandatory

string

The Customer Address Code for the Freight Payer that is the customer address (and associated customer account) that will be invoiced for the booking.

senderCode

optional

string

The Customer Address Code for the address from which the freight is originating. If this is not supplied then Sender Address details must be supplied in order to identify the Sender Code.

railOrigin

optional

string

The Location Code for the 'on rail' location from where the freight will travel. If not provided this will be derived from the Sender Code using the following rules. If the Sender Address is associated to a Siding, this will be the 'on rail' location linked to the Siding. If the Sender Address is not associated to a Siding then this will be the CT Site linked to the Sender Address.

exCTorSiding

optional

string

Determines whether the freight will travel from a Siding or a CT Site. If not supplied then this will default using the same rules as for railOrigin. If provided the Customer’s Sender Address must be associated to a siding in order to place an ex siding booking. Any sender address can request an ex CT booking.

doorPickupRequired

optional

boolean

For ex CT bookings defines whether the customer requires their freight to be collected from their sender address and transported to the CT site. Where this is required, door pickup details must also be provided to create the required transport orders.

senderAddress

optional

Optionally the customer can supply address details for the Sender Code to be derived from the Address. The Address Name and City must be supplied, Suburb is optional, in order to return a Customer Address Code.

senderAddressName

mandatory

string

The Customer Address Name that can be used to derive the Sender Code.

senderAddressSuburb

optional

string

The Customer Address Suburb that can be used to derive the Sender Code.

senderAddressCity

mandatory

string

The Customer Address Town/City that can be used to derive the Sender Code.

receiverCode

optional

string

The Customer Address Code for the address to which the freight is destined. If this is not supplied then Receiver Address details must be supplied in order to identify the Receiver Code.

railDestination

optional

string

The Location Code for the 'on rail' location to where the freight will travel. If not provided this will be derived from the Receiver Code using the following rules. If the Receiver Address is associated to a Siding, this will be the 'on rail' location linked to the Siding. If the Receiver Address is not associated to a Siding then this will be the CT Site linked to the Receiver Address City.

toCTorSiding

optional

string

Determines whether the freight will travel to a Siding or a CT Site. If not supplied then this will default using the same rules as for railDestination. If provided the Customers Receiver Address must be associated to a siding in order to place a to siding booking. Any receiver address can request a to CT booking.

doorDropoffRequired

optional

boolean

For to CT bookings defines whether the customer requires their freight to be collected from the CT Site and delivered to their receiver address. Where this is required, door dropoff details must also be provided to create the required transport orders.

receiverAddress

optional

Optionally the customer can supply address details to derive the Receiver Code from the Address. The Address Name and City must be supplied, Suburb is optional, in order to return a Customer Address Code.

receiverAddressName

mandatory

string

The Customer Address Name that can be used to derive the Receiver Code.

receiverAddressSuburb

optional

string

The Customer Address Suburb that can be used to derive the Receiver Code.

receiverAddressCity

mandatory

string

The Customer Address Town/City that can be used to derive the Receiver Code.

freightAvailable

mandatory

string

The date and time when the freight will be available to travel. For an exCT booking this is the date and time that the freight will be at the CT site. For siding freight this is the time the freight will be loaded and ready to travel.

freightRequiredAtDestination

mandatory

string

The date and time when the customer requires the freight to arrive at the on rail destination. For a toCT booking this is the date and time that the freight will be required to reach the CT site. For toSiding bookings this should be when the wagons are required to reach the nearest rail terminal.

scheduleBooking

boolean

string

true/false indicates whether the booking needs to be scheduled or left as an unscheduled booking. Phase 1 of EDI bookings this will always be 'N' as the bookings will be manually scheduled.

scheduleTo

optional

string

freightAvailable' or 'freightRequiredAtDestination' indicates whether the booking needs to be scheduled to when the freight is available to travel or to when the freight is required at destination. Typically inbound empty supply will be scheduled to the service that gets the equipment to destination by when it is required at destination whereas outbound loads will be booked to the first service departing after the freight is available to travel.

scheduleWaitlistOK

optional

boolean

true/false indicates whether it is ok for the booking to be waitlisted if there is no available capacity and the service allows waitlisting. This option will only be used where the customer is set up to allow 'waitlisting'

scheduleFirstOnly

optional

boolean

true/false indicates whether to only allow scheduling against the 'first' service that satisfies the customer requirement. Where 'true' it will not search for services with available capacity but rather attempt to book to the 'first' service that meets the requirement. If no capacity is available it will check whether waitlisting is allowed. If it is, it will waitlist, else it will reject the booking with 'No Capacity Available'.

customerReference

mandatory

string

The customer reference for the booking, typically this will be the Customer Purchase Order Number. This will be treated as a mandatory field where the customer is set up as 'Customer Reference required'.

releaseNumber

optional

string

The Shipping line booking reference which is used to release empty container from the container park and supplied to the Port when delivering freight to be shipped.

commodity

mandatory

string

The commodity code for the freight to be moved in the booking.

equipmentCategory

optional

string

Wagon/Container indicates the type of equipment being booked.

doorPickUp

Indicates whether any transport orders are to be created to transport the empty/loaded container at origin

moveType

mandatory

string

origin

empty

mandatory

boolean

true/false indicates whether this is an empty or loaded container

pickUpDateTime

mandatory

string

The date and time that the container is to be picked up, either at the customer site for a loaded container, or at the container supply site for an empty container.

deliveryDateTime

optional

string

The date and time that the container is to be picked up, either at the KR CT Site for a loaded container, or at the customer site for an empty container.

doorDropOff

optional

Indicates whether any transport orders are to be created to transport the empty/loaded container at destination

moveType

mandatory

string

destination

empty

mandatory

boolean

true/false indicates whether this is an empty or loaded container

pickUpDateTime

optional

string

The date and time that the container is to be picked up, either at the customer site for a loaded container, or at the container supply site for an empty container

deliveryDateTime

mandatory

string

The date and time that the container is to be picked up, either at the KR CT Site for a loaded container, or at the customer site for an empty container.

equipmentAttributes

mandatory

At least one equipment line must exist for a booking

equipmentGroup

optional

string

The KiwiRail Equipment Group code of the equipment to be booked. Where the equipment is not KiwiRail supply the customer can specify the Equipment Group and the Equipment Class will default. If the Equipment class is provided the Equipment Group will default from the Class. This must be one of the valid values - refer  'EquipmentGroup'

equipmentClass

optional

string

The KiwiRail Equipment Class code of the equipment to be booked. This must be provided where the equipment is to be supplied by KiwiRail else it may be defaulted from the Equipment Group. This must be one of the valid values  - refer  'EquipmentClass'

quantity

optional

integer

The quantity of this group, class and weight of equipment and commodity to be booked

netWeight

mandatory

integer

The net weight of the freight being booked. This must be supplied but may be 0 where the commodity is empty.

reefer

optional

boolean

true/false indicates whether it is reefer commodity being booked. Where this is 'true' reefer attributes must be supplied for the equipment.

hazardous

optional

boolean

true/false indicates whether it is hazardous commodity being booked. Where this is 'true' haz attributes may be supplied for the equipment.

KiwiRailSupplyIndicator

optional

boolean

true/false indicates whether the equipment is to be supplied by KiwiRail. For wagon bookings this will always be 'true' .

OrderNumber

optional

string

A customer supplied order number for this equipment

equipmentID

optional

string

The identifier for the equipment line. This is the container or wagon ID to be moved.

underBond

optional

boolean

Indicates whether the container is under bond.

reeferAttributes

optional

Where the equipment is 'reefer' the following information must be supplied

setTemperature

mandatory

number

The temperature that the container is to be set at.

allowedTimeOffPower

optional

number

The maximum amount of time that the container is allowed to be off power. This is cumulative and is not reset when the container is plugged in.

requiresGenerator

mandatory

boolean

true/false indicates whether the freight being transported is 'refrigerated' commodity which requires a generator (so that it does not exceed the maximum time off power)

KRSupply

optional

boolean

true/false where a generator is required this indicates whether the generator is to be supplied by KiwiRail.

hazAttributes

optional

Where the equipment is 'hazardous' the following information may be supplied. Only one haz class and UN code can be supplied for a booking request.

hazClass

mandatory

string

The haz class of the commodity

un

mandatory

string

The haz UN code of the commodity

kiwiRailSupplyAttributes

optional

supplyDateTime

mandatory

string

Where KiwiRail is to supply the equipment this is the date and time that it is required to be supplied. This is required where the kiwiRailSupplyIndicator is true.

imexAttributes

optional

Where the booking is for Imports or Exports the shipping details can be captured

ship

optional

string

The ship that the freight is on (for inbound) or booked to (outbound)

shipOperator

optional

string

The shipping line that operates the ship

shipCutOffDateTime

optional

string

For export, the time that the freight must reach the Port

voyageNumber

optional

string

The voyage number for the ship sailing

nzPort

optional

string

The NZ Port that the freight is inbound to, or outbound from

customsClearanceNumber

optional

string

For imports, the NZ customs clearance number for clearing the goods from the Port

overseasDestination

optional

string

For exports, the overseas Port to which the freight is destined

bookerEmail

optional

string

If the booker requires a booking confirmation to be emailed then they must supply an email address to send this to (For Production, please use the DTL EDI booking confirmation email address)

senderEmail

optional

string

If the sender requires a booking confirmation to be emailed then they must supply an email address to send this to

recieverEmail

optional

string

If the receiver requires a booking confirmation to be emailed then they must supply an email address to send this to

scheduleServices

optional

string

Schedule to Service list

serviceID

mandatory

string

The Service Identifier for the service the equipment to book to

Header

Value

Data Type

Comment

Version *requrired

1

integer

The version of this message format.

transactionID

FONTERRA_20171107131313_3dc7ffca-fd28-49ba-9636-1ff66bfe5341

string

An unique identifier for a set of messages belonging to each other. Can be null if there is no transaction ID attached to this message. Identifier is defined as <app>_<initiator>_<timestamp>_UUID for example

messageID

string

Unique identifier for this message. This is similar to the Mule ESB MessageID who would use this id internally. The message ID should only exist for the message between two systems, so a stream over three components will use two messageIDs one for component A to B and one from B to C. This value cannot be set by the caller.

currentSystem

Fonterra Bookings

string

System that generated the message

userInitiatingRequest

email

string

User requesting/submitting information Login ID

creationTimestamp *required

2017-11-07 13:13:13:123 NZDT

string

Date of creation of the message in YYYY-MM-DD hh:mm:ss:ms in NZDT

auditCategory

string

string

Holds a string that can be used to collect log information over all services

payloadEncrypted

Boolean

boolean

If true the payload is encrypted, when false it is not. This is set for the content encryption(like GPG), not the connection (like SSL)

payloadEncoding

string

string

When the payload is text, it should contain the text encoding (Like 'UTF-8'), if binary, the encoding is binary When the payload is encrypted, the encoding should be the encoding of the unencrypted payload. If the payload type is not known, or not disclosed, the value is passthrough

debug

0

integer

Logs all requests if set in debug mode 0 - Don't debug 1 - Debug mode

retryNumber

0

integer

Attempts made by calling service to read content

Cache-Control

no-cache

string

Recommended caching time for services to expire (When data should be refreshed.) (When data should be refreshed.) The directives can be used max-age, s-max-age, private/public, no-cache, no-store, must-revalidate, proxy-revalidate

previousID

string

If this is a next message in a communication sequence, the message that triggered this one. For instance, message ‘aa’ created this message ‘bb’ the PreviousID equals 'aa’. If this is the first message, the value is null

payloadSignature

string

Optional payload signature for cases where nonrepudiation is required.

Field

Required?

Data Type

Description

bookingID

mandatory

string

A unique ID to be generated by CTMS

bookingSource

optional

string

Identifies the channel by which the booking was received, for example, email, phone, EDI.

bookingReference

mandatory

string

A customer supplied reference that uniquely identifies this booking request.

bookingType

optional

string

The type of booking to be created, standard, repeat master (recurring booking), cash sale, service recovery. The default for EDI bookings will be ‘Standard’

bookerCode

mandatory

string

The Customer Address Code for the party requesting the booking.

freightPayerCode

mandatory

string

The Customer Address Code for the Freight Payer, that is the customer address (and associated customer account) that will be invoiced for the booking.

senderCode

optional

string

The Customer Address Code for the address from which the freight is originating. If this is not supplied then Sender Address details must be supplied in order to identify the Sender Code.

railOrigin

optional

string

The Location Code for the 'on rail' location from where the freight will travel. If not provided this will be derived from the Sender Code using the following rules. If the Sender Address is associated to a Siding, this will be the 'on rail' location linked to the Siding. If the Sender Address is not associated to a Siding then this will be the CT Site linked to the Sender Address.

exCTorSiding

optional

string

Determines whether the freight will travel from a Siding or a CT Site. If not supplied then this will default using the same rules as for railOrigin. If provided the Customer’s Sender Address must be associated to a siding in order to place an ex siding booking. Any sender address can request an ex CT booking.

doorPickupRequired

optional

boolean

For ex CT bookings defines whether the customer requires their freight to be collected from their sender address and transported to the CT site. Where this is required, door pickup details must also be provided to create the required transport orders.

senderAddress

optional

Optionally the customer can supply address details for the Sender Code to be derived from the Address. The Address Name and City must be supplied, Suburb is optional, in order to return a Customer Address Code.

senderAddressName

mandatory

string

The Customer Address Name that can be used to derive the Sender Code.

senderAddressSuburb

optional

string

The Customer Address Suburb that can be used to derive the Sender Code.

senderAddressCity

mandatory

string

The Customer Address Town/City that can be used to derive the Sender Code.

receiverCode

optional

string

The Customer Address Code for the address to which the freight is destined. If this is not supplied then Receiver Address details must be supplied in order to identify the Receiver Code.

railDestination

optional

string

The Location Code for the 'on rail' location to where the freight will travel. If not provided this will be derived from the Receiver Code using the following rules. If the Receiver Address is associated to a Siding, this will be the 'on rail' location linked to the Siding. If the Receiver Address is not associated to a Siding then this will be the CT Site linked to the Receiver Address City.

toCTorSiding

optional

string

Determines whether the freight will travel to a Siding or a CT Site. If not supplied then this will default using the same rules as for railDestination. If provided the Customers Receiver Address must be associated to a siding in order to place a to siding booking. Any receiver address can request a to CT booking.

doorDropoffRequired

optional

boolean

For to CT bookings defines whether the customer requires their freight to be collected from the CT Site and delivered to their receiver address. Where this is required, door dropoff details must also be provided to create the required transport orders.

receiverAddress

optional

Optionally the customer can supply address details to derive the Receiver Code from the Address. The Address Name and City must be supplied, Suburb is optional, in order to return a Customer Address Code.

receiverAddressName

mandatory

string

The Customer Address Name that can be used to derive the Receiver Code.

receiverAddressSuburb

optional

string

The Customer Address Suburb that can be used to derive the Receiver Code.

receiverAddressCity

mandatory

string

The Customer Address Town/City that can be used to derive the Receiver Code.

freightAvailable

mandatory

string

The date and time when the freight will be available to travel. For an exCT booking this is the date and time that the freight will be at the CT site. For siding freight this is the time the freight will be loaded and ready to travel.

freightRequiredAtDestination

mandatory

string

The date and time when the customer requires the freight to reach destination. For a toCT booking this is the date and time that the freight will be required to reach the CT site. For toSiding bookings this should be when the wagons are required to be placed at the siding.

scheduleBooking

optional

boolean

true/false indicates whether the booking needs to be scheduled or left as an unscheduled booking.

scheduleTo

optional

string

freightAvailable' or 'freightRequiredAtDestination' indicates whether the booking needs to be scheduled to when the freight is available to travel or to when the freight is required at destination. Typically inbound empty supply will be scheduled to the service that gets the equipment to destination by when it is required at destination whereas outbound loads will be booked to the first service departing after the freight is available to travel.

scheduleWaitlistOK

optional

boolean

true/false indicates whether it is ok for the booking to be waitlisted if there is no available capacity and the service allows waitlisting. This option will only be used where the customer is set up to allow 'waitlisting'

scheduleFirstOnly

optional

boolean

true/false indicates whether to only allow scheduling against the 'first' service that satisfies the customer requirement. Where 'true' it will not search for services with available capacity but rather attempt to book to the 'first' service that meets the requirement. If no capacity is available it will check whether waitlisting is allowed. If it is, it will waitlist, else it will reject the booking with 'No Capacity Available'.

customerReference

mandatory

string

The customer reference for the booking, typically this will be the Customer Purchase Order Number.

releaseNumber

optional

string

The Shipping line booking reference which is used to release empty container from the container park and supplied to the Port when delivering freight to be shipped.

Commodity

mandatory

string

The commodity code for the freight to be moved in the booking.

equipmentCategory

optional

string

Wagon/Container indicates the type of equipment being booked.

doorPickUp

optional

Indicates whether any transport orders are to be created to transport the empty/loaded container at origin

moveType

mandatory

string

origin

empty

mandatory

boolean

true/false indicates whether this is an empty or loaded container

pickUpDateTime

mandatory

string

The date and time that the container is to be picked up, either at the customer site for a loaded container, or at the container supply site for an empty container.

deliveryDateTime

optoinal

string

The date and time that the container is to be picked up, either at the KR CT Site for a loaded container, or at the customer site for an empty container.

doorDropOff

optional

Indicates whether any transport orders are to be created to transport the empty/loaded container at destination

moveType

mandatory

string

destination

empty

mandatory

boolean

true/false indicates whether this is an empty or loaded container

pickUpDateTime

string

The date and time that the container is to be picked up, either at the customer site for a loaded container, or at the container supply site for an empty container

deliveryDateTime

mandatory

string

The date and time that the container is to be picked up, either at the KR CT Site for a loaded container, or at the customer site for an empty container.

equipmentAttributes

mandatory

At least one equipment line must exist for a booking

equipmentGroup

optional

string

The KiwiRail Equipment Group code of the equipment to be booked. Where the equipment is not KiwiRail supply the customer can specify the Equipment Group and the Equipment Class will default. If the Equipment class is provided the Equipment Group will default from the Class. This must be one of the valid values - refer  'EquipmentGroup'

equipmentClass

optional

string

The KiwiRail Equipment Class code of the equipment to be booked. This must be provided where the equipment is to be supplied by KiwiRail else it may be defaulted from the Equipment Group. This must be one of the valid values  - refer  'EquipmentClass'

quantity

optional

integer

The quantity of this group, class and weight of equipment and commodity to be booked

netWeight

mandatory

integer

The net weight of the freight being booked. This must be supplied but may be 0 where the commodity is empty.

reefer

optional

boolean

true/false indicates whether it is reefer commodity being booked. Where this is 'true' reefer attributes must be supplied for the equipment.

hazardous

optional

boolean

true/false indicates whether it is hazardous commodity being booked. Where this is 'true' haz attributes may be supplied for the equipment.

kiwiRailSupplyIndicator

optional

boolean

true/false indicates whether the equipment is to be supplied by KiwiRail. For wagon bookings this will always be 'true' .

orderNumber

optional

string

A customer supplied order number for this equipment

equipmentID

optional

string

The identifier for the equipment line. This is the container or wagon ID to be moved.

underBond

optional

boolean

Indicates whether the container is under bond

reeferAttributes

optional

Where the equipment is 'reefer' the following information must be supplied

setTemperature

mandatory

number

The temperature that the container is to be set at.

allowedTimeOffPower

optional

number

The maximum amount of time that the container is allowed to be off power. This is cumulative and is not reset when the container is plugged in.

requiresGenerator

mandatory

boolean

true/false indicates whether the freight being transported is 'refrigerated' commodity which requires a generator (so that it does not exceed the maximum time off power)

KRSupply

optional

boolean

true/false where a generator is required this indicates whether the generator is to be supplied by KiwiRail.

hazAttributes

optional

Where the equipment is 'hazardous' the following information may be supplied. Only one haz class and UN code can be supplied for a booking request.

hazClass

mandatory

string

The haz class of the commodity

Un

mandatory

string

The haz UN code of the commodity

scheduleDetails

optional

Where the equipment has been scheduled the schedule details

serviceCutOffDateTime

mandatory

string

This is the date and time that the equipment needs to be checked in at the CT site for ex CT bookings, or manifest received by for ex siging bookings in order for it to travel on the sceduled service

arrivalAtDestinationDateTime

mandatory

string

The time the equipment is scheduled to arrive at the destination Rail Terminal

expectedAtDestinationDateTime

mandatory

string

The time the equipment is scheduled to be released to the customer at destination

waitlisted

mandatory

boolean

true/false indicates whether the equipment has been waitlisted or conformed on the Service

kiwiRailSupplyAttributes

optional

supplyDateTime

mandatory

string

Where KiwiRail is to supply the equipment this is the date and time that it is required to be supplied. This is required where the kiwiRailSupplyIndicator is true.

imexAttributes

optional

Where the booking is for Imports or Exports the shipping details can be captured

ship

optional

string

The ship that the freight is on (for inbound) or booked to (outbound)

shipOperator

optional

string

The shipping line that operates the ship

shipCutOffDateTime

optional

string

For export, the time that the freight must reach the Port

voyageNumber

optional

string

The voyage number for the ship sailing

nzPort

optional

string

The NZ Port that the freight is inbound to, or outbound from

customsClearanceNumber

optional

string

For imports, the NZ customs clearance number for clearing the goods from the Port

overseasDestination

optional

string

For exports, the overseas Port to which the freight is destined

bookerEmail

optional

string

If the booker requires a booking confirmation to be emailed then they must supply an email address to send this to

senderEmail

optional

string

If the sender requires a booking confirmation to be emailed then they must supply an email address to send this to

recieverEmail

optional

string

If the receiver requires a booking confirmation to be emailed then they must supply an email address to send this to

Header

Value

Data Type

Comment

version

1

integer

The version of this message format.

transactionID

FONTERRA_20171107131313_3dc7ffca-fd28-49ba-9636-1ff66bfe5341

string

An unique identifier for a set of messages belonging to each other. Can be null if there is no transaction ID attached to this message. Identifier is defined as <app>_<initiator>_<timestamp>_UUID for example

messageID

string

Unique identifier for this message. This is similar to the Mule ESB MessageID who would use this id internally. The message ID should only exist for the message between two systems, so a stream over three components will use two messageIDs one for component A to B and one from B to C. This value cannot be set by the caller.

currentSystem

Fonterra Bookings

string

System that generated the message

userInitiatingRequest

email

string

User requesting/submitting information Login ID

creationTimestamp

2017-11-07 13:13:13:123 NZDT

string

Date of creation of the message in YYYY-MM-DD hh:mm:ss:ms in NZDT

auditCategory

string

string

Holds a string that can be used to collect log information over all services.

payloadEncrypted

Boolean

boolean

If true the payload is encrypted, when false it is not. This is set for the content encryption(like GPG), not the connection (like SSL)

payloadEncoding

string

string

When the payload is text, it should contain the text encoding (Like 'UTF-8'), if binary, the encoding is binary When the payload is encrypted, the encoding should be the encoding of the unencrypted payload. If the payload type is not known, or not disclosed, the value is pass-through

debug

0

integer

Logs all requests if set in debug mode 0 - Don't debug 1 - Debug mode

retryNumber

0

integer

Attempts made by calling service to read content

Cache-Control

no-cache

string

Recommended caching time for services to expire (When data should be refreshed) (When data should be refreshed) The directives can be used max-age, s-max-age, private/public, no-cache, no-store, must-revalidate, proxy-revalidate