Booking API Validation

Source Ref

String

Unique Booking Reference from the client’s source system

Mandatory.

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 should 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.

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

Optional

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 there is already a Booking in the system with this same External Matching Ref value that is NOT already Cancelled, this message should 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.

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

Mandatory

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, and must only be present if Booking Reason = SALES ORDER. It must also refer to a valid Source Ref for a Booking with Booking Reason = ASN or GOODS TRANSFER

Is Return

Boolean

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

Optional

Must only be present if Booking Reason = GOODS TRANSFER

FALSE

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

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, where the Role is each section is distinct i.e. no repeated roles.

Default / Enrichment Flow logic must complete without errors

External Code

String

Unique Organisation Reference according to the client’s source system

Mandatory for each Organisation instance present

Name

String

Organisation Name according to the client’s source system

Mandatory for each Organisation instance present

See Enrichments processing above, that relies on determining the Client and then looking up Master Data against that Client

City

String

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

Mandatory for each Organisation instance present

Country

String

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

Mandatory for each Organisation instance present

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.

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

Must be at least one Goods Section

Description

String

Free-format description of this item of Goods

Must be present if SKU is not present

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

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

Condition

Enumeration

NEW, USED, DAMAGED

The condition of the goods, see enumerated values

Optional, only applicable for Booking Reason = GOODS TRANSFER

NEW

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

Quantity Unit

Enumeration

PKG, PCS, CTN

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

Must be present if Quantity is present

Inner Quantity

Integer

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

Must be present if Outer Quantity is present

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

Outer Quantity

Integer

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

Must be present if Inner Quantity is present

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

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

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

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

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

Volume Unit

M3

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

Must be present if Volume is present

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

Description

String

Free-format description of this item of Child Goods

Must be present if (child) SKU is not present

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

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

Transit Mode

Enumeration

ROAD, SEA, AIR, RAIL, PARCEL

Mode of Transport

Mandatory if this section is present

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

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. If multiple Container sections provided, each must refer to a different Container Type

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

Number of Containers

Integer

The number of containers that will be required of this type

Mandatory if this section is present

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

Enrichment flow logic must complete without errors

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

See above

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

Enrichment flow logic must complete without errors

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

See above

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

Enrichment flow logic must complete without errors

If the Booking Reason = GOODS TRANSFER, and the Collection Location section is not included, there must be a default Collection Location instance set up within the Booking Master Data of the Client Organisation (determined above)

(This will typically be the usual source Factory location of that Client).

The Collection Location fields (below) will then be fully populated from that configured Location instance.

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 above

Contact

Contact Info Type

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

Optional

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

See above

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

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

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

Country Code

String

2-letter Country ISO Code

Optional, but must be present if no Location Code provided

Contact Name

String

Name of the contact at the corresponding location

Mandatory if this section is present

email Address

String

email address of that contact

Optional, must be a valid email address format if present

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

Earliest

Date-Time

Earliest date/time that collection is expected to occur

Optional

If omitted, set equal to Latest

Latest

Date-Time

Latest date/time that collection is expected to occur

Mandatory if this section is present

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

Enrichment flow logic must complete without errors

If the Booking Reason = ASN or GOODS TRANSFER, and the Delivery Location section is not included, there must be a default Delivery Location instance set up within the Booking Master Data of the Client Organisation (determined above)

(This will typically be the usual destination SEKO Warehouse for all inbound bookings and ASNs).

The Delivery Location fields (below) will then be fully populated from that configured Location instance.

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 above

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

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

Earliest

Date-Time

Earliest date/time that delivery is expected to occur

Optional

If omitted, set equal to Latest

Latest

Date-Time

Latest date/time that delivery is expected to occur

Mandatory

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

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

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 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. If this condition is not met, it will flag the error condition "Previous Booking not found or already Cancelled" and no changes will be made and no new Booking will be created. If this condition is met, all contents in this API message will be applied to that earlier booking instance.

If this section is missing, but there is already a Booking in the system with this same matching key value that is NOT already Cancelled, then it is being treated as a change (see main Header section).

If this situation occurs, see below for default/ enrichment of the Booking Change details

Reason

Enumeration

CANCELLED BY END CUSTOMER, CANCELLED BY CLIENT, AMENDMENT

Reason for the change

Mandatory if this section is present

If a booking update has occurred (see above) but this section was missing, introduce this section and populate this field with AMENDMENT

Additional Info

String

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

Optional