White Glove Bookings API

Source Ref

String

Unique Booking Reference from the client’s source system

If the External Matching Ref (below) is NOT present, ‘Source Ref’ is the matching key for the Booking.

As per the current Voyager system, if there is already a Booking in the system with this same Source Ref value that is NOT already Cancelled, this message will be treated as an Update (plus see Enrichment for the ‘Booking Change’ section below)

Otherwise this API message will be treated as a NEW Booking.

Mandatory

Source Ref is missing

External Matching Ref

String

Another unique Booking Reference from the client’s source system which they use for their external matching & external communications (if different from their source ref). This is here to support existing bookings being received from other clients.

If present, ‘External Matching Ref’ is assumed to be the matching key for this Booking (to support current implementations).

As per the current Voyager system, if this value is populated and if there is already a Booking in the system with this same External Matching Ref value that is NOT already Cancelled, this message will be treated as an Update (plus see Enrichment for the ‘Booking Change’ section below)

Otherwise this API message will be treated as a NEW Booking.

Optional

Booking Reason

Enumeration

ASN, GOODS TRANSFER, SALES ORDER

The reason for the booking:

ASN: notify SEKO of inbound goods into SEKO’s warehouse but the client will arrange transport

GOODS TRANSFER: booking for SEKO to arrange transport of goods from client premises (e.g. the factory) to a SEKO warehouse. Could also be used to book transfer of goods from any type of location to any other type of location that is not in relation to a Sales Order.

SALES ORDER: booking for SEKO to fulfil a client’s Sales Order by collecting goods from a location (typically SEKO’s own warehouse) and deliver to the client’s end customer’s site, and possibly to install & quality-check via our White Glove partner services

Must be one of the enumerated values¹

Mandatory²

¹Unrecognised Booking Reason

²Booking Reason is missing

Allocate Goods From Ref

String

The Source Booking Reference of a separate ASN or GOODS TRANSFER booking, which is intended by the Client to supply the necessary Goods to fulfil this SALES ORDER booking

Optional, but must only be present if Booking Reason = SALES ORDER.

Allocate Goods From Ref is present but this is not a SALES ORDER booking

Is Return

Boolean

If TRUE, the goods need to be moved because they are being returned by the end customer

Optional, but must only be present if Booking Reason = GOODS TRANSFER

Is Return is present but this is not a GOODS TRANSFER booking

Incoterms

Enumeration

EXW, FCA, CPT, CIP, DPU, DAP, DDP, FAS, FOB, CFR, CIF

The client may wish to inform us of the required Incoterms (i.e. the split of costs between Consignor and Consignee for the movement of goods)

Optional

Must be one of the enumerated values

Unrecognised Incoterms

Incoterms Location

String

The client may wish to inform us of the relevant location for which the Incoterms are assumed to apply e.g. the name of the origin or destination port

Optional

Source Creation Time

Date-Time

The timestamp at which the booking had been created in the client’s source system

Optional

Lists the official Organisations involved in the booking; Consignor, Consignee and Client

There must be a maximum of three Organisation sections

More than three Organisations have been provided

External Code

String

Unique Organisation Reference according to the client’s source system

Mandatory for each Organisation instance present

Organisation Code is missing

Name

String

Organisation Name according to the client’s source system

Mandatory for each Organisation instance present

Organisation Name is missing

City

String

Organisation’s registered City according to the client’s source system

Mandatory for each Organisation instance present

Organisation City is missing

Country

String

Organisation’s registered country using the standard 2-letter country ISO Code

Mandatory¹ for each Organisation instance present

Must be a valid 2-letter country ISO code²

¹Organisation Country is missing

²Organisation’s Country is not a valid ISO Code

Role

Enumeration

CONSIGNOR, CONSIGNEE, CLIENT

Organisation’s Role in this booking; either the Consignor, the Consignee, or the Client

Mandatory for each Organisation instance present¹

Must be one of the enumerated values²

Value must not be repeated in any other Organisation section³

¹Organisation Role is missing

²Unrecognised Organisation Role

³Two or more Organisations have the same Role

Lists the individual Goods items within the Booking; one Goods Section for each separate item

Must be at least one Goods Section

Goods definition is missing

Description

String

Free-format description of this item of Goods

Must be present if SKU is not present

Both Goods SKU and Goods Description are missing

SKU

String

SKU code for this item of Goods

Must be present if Description is not present

Sales Order Line ID

String

Line ID from the Sales Order that corresponds to this item of Goods

Optional, only applicable for Booking Reason = SALES ORDER

Sales Order Line ID is present but this is not a SALES ORDER booking

Quantity

Quantity Type

Quantity measure for this Goods item, which can be expressed in various ways, see below

Mandatory, but see below for more details

(see below)

Condition

Enumeration

NEW, USED, DAMAGED

The condition of the goods, see enumerated values

Optional, only applicable for Booking Reason = GOODS TRANSFER¹

Must be one of the enumerated values²

¹Goods Condition is present but this is not a GOODS TRANSFER

²Unrecognised Goods Condition

Quantity

Integer

The number of pieces, packages, cartons etc for this Goods Item

Must be present if no Gross / Net Weight and no Volume and no Inner / Outer Quantities are present

No Goods Quantity, Weight or Volume has been specified

Quantity Unit

Enumeration

PKG, PCS, CTN

The ‘units’ of the quantity i.e. pieces, packages or cartons

Must be present if Quantity is present

Goods Quantity is present but no Quantity Unit

Inner Quantity

Integer

The number of inner pieces, packages, cartons etc for this Goods Item

Must be present if Outer Quantity is present

Goods Inner Quantity is present but no Outer Quantity

Inner Quantity Unit

Enumeration

PKG, PCS, CTN

The ‘units’ of the inner quantity i.e. pieces, packages or cartons

Must be present if Inner Quantity is present

Goods Inner Quantity is present but no Inner Quantity Unit

Outer Quantity

Integer

The number of outer pieces, packages, cartons etc for this Goods Item

Must be present if Inner Quantity is present

Goods Outer Quantity is present but no Inner Quantity

Outer Quantity Unit

Enumeration

PKG, PCS, CTN

The ‘units’ of the outer quantity i.e. pieces, packages or cartons

Must be present if Outer Quantity is present

Goods Outer Quantity is present but no Outer Quantity Unit

Gross Weight

Float

The gross weight including packaging of this Goods item

Must be present if no Net Weight and no Volume and no Quantity and no Inner / Outer Quantities are present

(covered by ‘Quantity’ error condition above)

Net Weight

Float

The net weight excluding packaging of this Goods item

Must be present if no Gross Weight and no Volume and no Quantity and no Inner / Outer Quantities are present

(covered by ‘Quantity’ error condition above)

Weight Unit

KG, LB

The units that the Gross or Net Weight is expressed in

Must be present if either Gross or Net Weight are present

Goods Gross or Net Weight is present but no Weight Unit

Volume

Float

The volume taken up by this Goods item

Must be present if no Gross / Net Weight and no Quantity and no Inner / Outer Quantities are present

(covered by ‘Quantity’ error condition above)

Volume Unit

M3

The units that the volume is expressed in (currently only m³ supported)

Must be present if Volume is present

Goods Volume is present but no Volume Unit

Lists the individual Child Goods items within each of the Goods Sections if applicable; one Child Goods Section for each separate main Goods item

Multiple Child Goods sections are permitted for each main Goods section, but must only be present when Booking Reason = SALES ORDER

Child Goods are specified but this booking is not a SALES ORDER

Description

String

Free-format description of this item of Child Goods

Must be present if (child) SKU is not present

Both Goods SKU and Goods Description are missing in Child Goods

SKU

String

SKU code for this item of Child Goods

Must be present if (child) Description is not present

Quantity

Quantity Type

Quantity measure for this Child Goods item, which can be expressed in various ways, see Quantity Type definition for main Goods above

Mandatory, but see above for more details

(see above Quantity Type validation, but messages when validation fails prefixed by “Child “)

Lists the mode of transport of the goods and container mode and provides extra information about how the goods will be (or should be) transported

This entire section is optional but MUST be specified if Booking Reason = ASN

Booking Reason is ASN but no Transit details section has been specified

Transit Mode

Enumeration

ROAD, SEA, AIR, RAIL, PARCEL

Mode of Transport

Mandatory if this section is present¹

Must be one of the enumerated values²

¹Transit Mode is missing

²Unrecognised Transit Mode

Container Mode

Enumeration

FTL, LTL, FCL, LCL, ULD, LOOSE, BCN, LSE

The possible container operational models that may apply based on the selected Transit Mode above, as follows:

ROAD: FTL, LTL

SEA: FCL, LCL, BCN

AIR: LSE, ULD

PARCEL: LSE

RAIL: FCL, LSE

Optional, but if present, must only take the following values dependent on the selected Transit Mode:

ROAD: FTL, LTL

SEA: FCL, LCL, BCN

AIR: LSE, ULD

PARCEL: LSE

RAIL: FCL, LSE

Container Mode is specified but is not applicable to the Transit Mode

Additional Info

String

Additional information about the method of goods transit, if required

Optional

Within the Transit section, there can be several instances of the Containers Section, each stating the type of container required for the transport of the goods and how many of this container type

This entire section is optional, and only needed if the Container Type needs to be specified for the transport of the goods.

Container Type

Enumeration

See list of Container Types below

The type of container used (currently only supports Road transport)

Mandatory if this section is present¹

Must be one of the valid Container Type Codes (see below)²

If multiple Container sections provided, each must refer to a different Container Type³

¹Container Type is missing

²Unrecognised Container Type

³Two or more Containers have the same Container Type

Number of Containers

Integer

The number of containers that will be required of this type

Mandatory if this section is present¹, and must be an integer value²

¹Number of Containers is missing

²Number of Containers is not an integer

RDMEG

Road Mega Trailer

RDMEGSR

Road Mega Trailer with sliding roof

RDTRN

Road Train

45HC

45ft High Cube

40HC

40ft High Cube

40GP

40ft General Purpose

20GP

20ft General Purpose

LTL

Less than truck load

RDCUR

Road Curtain Sider

This section provides an external Agent Code representing the Agent organisation who will be handing over the goods to SEKO at the start of SEKO’s responsibility. For example, when an inbound ASN notifies SEKO of goods arriving at their warehouse, this informs SEKO who the Carrier is. It also allows any other relevant information to be provided as free-form text.

This entire section is optional, but must be provided if the Booking Reason = ASN

Booking Reason is ASN but Receive From Section is missing

Agent Code

String

The external code of the ‘receive from’ agent (e.g. Carrier), from SEKO’s perspective, at the start of the part of the flow that is under SEKO’s responsibility

Mandatory if this section is present

Receive From Agent Code is missing

Agent Name

String

The free-format name of the ‘receive from’ agent, according to the client

Mandatory if this section is present

Receive From Agent Name is missing

Additional Info

String

Any other information that SEKO needs to know about the Receive From agent

Optional

This section provides an external Agent Code representing the Agent organisation who SEKO must hand the goods over to, at the end of SEKO’s responsibility. For example, when an outbound SALES ORDER requires SEKO to release the goods only, to another Carrier or White Glove Logistics provider. It also allows any other relevant information to be provided as free-form text.

This entire section is optional, and must not be present if the Booking Reason = ASN

Booking Reason is ASN but Handover To Section has been specified

Agent Code

String

The external code of the ‘handover to’ agent (e.g. Carrier), from SEKO’s perspective, at the end of the part of the flow that is under SEKO’s responsibility

Mandatory if this section is present

Handover To Agent Code is missing

Agent Name

String

The free-format name of the ‘handover to’ agent, according to the client

Mandatory if this section is present

Handover To Agent Name is missing

Additional Info

String

Any other information that SEKO needs to know about the Handover To agent

Optional

This section contains the location and contact details from where SEKO needs to arrange collection of the goods. This only applies for a GOODS TRANSFER (e.g. SEKO arranges collection at client’s factory) or for a SALES ORDER (e.g. SEKO arranges collection from a warehouse for delivery to end customer or White Glove partner).

This entire section is optional, and must NOT be present if the Booking Reason = ASN

Booking Reason is ASN but Collection Section has been specified

Location

Location Type

Location details at the collection point at the start of the flow under SEKO’s responsibility

Mandatory if this section is present

(see Location Type below, using ‘Collection’)

Contact

Contact Info Type

Contact details at the collection point at the start of the flow, if required

Optional

(see Contact Info Type below, using ‘Collection’)

Additional Info

String

Any other information that SEKO needs to know about the Collection point

Optional

Location Code

String

External (client-side) code for the Location, if required

Optional, but must be present if no Location Name provided

Missing <Collection / Delivery> Location Code and Location Name

Location Name

String

Name of the location e.g. site name, factory name, warehouse name etc

Optional, but must be present if no Location Code provided

Address Line 1

String

Line 1 of the location address

Optional, but must be present if no Location Code provided

Missing <Collection / Delivery> Location Address Line 1 and no Location Code

Address Line 2

String

Line 2 of the location address

Optional

City

String

Location’s City

Optional, but must be present if no Location Code provided

Missing <Collection / Delivery> Location City and no Location Code

Region

String

Location’s Region or County

Optional

Postcode / ZIP

String

Postcode or ZIP code

Optional, but must be present if no Location Code provided

Missing <Collection / Delivery> Postcode/ZIP Code and no Location Code

Country Code

String

2-letter Country ISO Code

Optional, but must be present if no Location Code provided¹

Must be a valid 2-letter Country ISO Code²

¹Missing <Collection / Delivery> Location Country and no Location Code

²<Collection / Delivery> Location Country is not a valid ISO Code

Contact Name

String

Name of the contact at the corresponding location

Mandatory if this section is present

Missing <Collection / Delivery> Contact Name

email Address

String

email address of that contact

Optional, must be a valid email address format if present

Invalid <Collection / Delivery> email address

Contact Number

String

Phone number of that contact

Optional

This section contains the time window within which Collection of the goods is expected by the client to take place

This entire section is optional, and must not be present if the Booking Reason = ASN¹

It MUST be present if the Booking Reason = GOODS TRANSFER²

¹Booking Reason is ASN but Collection Time Window section has been specified

²Booking Reason is GOODS TRANSFER but Collection Time Window section is missing

Earliest

Date-Time

Earliest date/time that collection is expected to occur

Optional

Latest

Date-Time

Latest date/time that collection is expected to occur

Mandatory if this section is present

Latest Collection Time is missing

Cargo Ready Date

Date

The date the goods are expected by the client to be fully manufactured

Optional

Ex Factory Date

Date

The date the goods are expected by the client to be ready to ship from the factory

Optional

This section contains the location and contact details to where SEKO needs to arrange delivery / handover of the goods.

This entire section is optional, but MUST be present if the Booking Reason = SALES ORDER

Booking Reason is SALES ORDER but Delivery Section is missing

Location

Location Type

Location details at the delivery point at the end of the flow under SEKO’s responsibility. See above for Location Type details.

Mandatory if this section is present

(see Location Type above, using ‘Delivery’)

Contact

Contact Info Type

Contact details at the delivery point at the end of the flow, if required. See above for Contact Info Type details

Optional

(see Contact Info Type above, using ‘Delivery’)

Additional Info

String

Any other information that SEKO needs to know about the Delivery point

Optional

This section contains the time window within which Delivery of the goods is expected by the client to take place

This entire section is mandatory

Delivery Time Window section is missing

Earliest

Date-Time

Earliest date/time that delivery is expected to occur

Optional

Latest

Date-Time

Latest date/time that delivery is expected to occur

Mandatory

Latest Delivery Time is missing

This section contains the details where the Client Booking can request for a White Glove service to be managed by SEKO

This section is optional, and must only be present where the Booking Reason = SALES ORDER

White Glove section is present in the booking, but the booking is not for a SALES ORDER

Assembly Required

TRUE/FALSE

Whether or not White Glove assembly of the product is required to be managed by SEKO

Mandatory if this section is present

White Glove Assembly Required is missing

Additional Info

String

Any other free-form text information about the White Glove install that SEKO needs to know about

Optional

This section contains information about any amendments or cancellation for a previously-sent Booking, that the Client wants to send to SEKO.

If this section is missing, but there is already a Booking in the system with the same matching key value that is NOT already Cancelled, then this booking will still be treated as an Amendment (see main Header section), for compatibility with existing booking feeds from other clients.

If this section is present, but validation fails, no changes will be made and no new Booking will be created.

If this section is present, and validation succeeds, all contents in this API message will be applied to that earlier booking instance.

If the External Matching Ref (below) is NOT present in the main booking header, Source Ref is the matching key for the Booking. Otherwise External Matching Ref is the matching key. (see main booking header section above)

If this section is present, the matching key value of this Booking must match the corresponding value in a previously-sent Booking which has not already been cancelled.

Previous Booking not found or already Cancelled

Reason

Enumeration

CANCELLED BY END CUSTOMER, CANCELLED BY CLIENT, AMENDMENT

Reason for the change

Mandatory if this section is present¹

Must be one of the enumerated values²

¹Booking Change Reason is missing

²Unrecognised Booking Change Reason

Additional Info

String

Any other free-form text information about change that SEKO needs to know about

Optional