Client Transport Order - EDI Portal Spotworx

CREATE Client Transport Order

messageType: transport.clientTransportOrder

Creates a transport order in our TMS visiblity platform.

The sample files are provided in 3 levels of detail: Small, Medium and Large. Small only contains the bare necessities needed to create an order in our system, whereas for large almost all possible fields of the respective modality are filled.

While it is possible to send us orders with only the minimum of data provided, it is highly recommended to provide as much information as possible.

Sample files

JSON XML

{
	"messageHeader":{...},
	"clientTransportOrder":{...}
}

Property	Type	Mandatory	Description
messageHeader	MessageHeader	M	Message Header information.
ClientTransportOrder	ClientTransportOrder	M	Transport Order

ClientTransportOrder

JSON XML

"...": {
  "businessDirection": "EXPORT",
  "cargoDescriptions": [{...}],
  "containerDefinition": {...},
  "customerAccountNumber": "string",
  "deliveryTerm": {...},
  "mainCategory": "FCL",
  "mainModality": "AIR",
  "orderDetails": {...},
  "participants": {...},
  "routingInformation": {...}
}

Property	Type	Mandatory	Description
customerAccountNumber	String	M	Your SPOT account number. This is used to associate the created order with your company or office.
mainModality	String	M	Modality of transport. Valid values: `AIR, ROAD, SEA, AIR_SEA, SEA_AIR`
mainCategory	String	C	Defines the subtype of the transport modality. Mandatory for SEA shipments. Valid values for ROAD: `FTL, LTL, GROUPAGE` Valid values for SEA: `FCL, LCL, REEFER`
businessDirection	String	M	Identifies direction of goods from principals viewpoint.Valid values: `IMPORT, EXPORT, TRIANGLE`
deliveryTerm	TransportDeliveryTerm	M	IncoTerm and Location
cargoDescriptions	Array[CargoDescription]	M	Transport cargo description. For FCL/REEFER per container.
orderDetails	OrderDetails	O	Additional detail information
containerDefinition	ContainerDefinition	C	Only applicable and mandatory for SEA FCL / REEFER. Mandatory for SEA event tracking.
participants	Participants	M	Parties participating in a transport
routingInformation	RoutingInformation	M	Information about the transport routing and dates
orderComment	OrderComment	O	comments regarding the Transport Order

OrderDetails

JSON XML

"...": {
    "insurance": {...},
    "paymentDefinition": {...},
    "references": [{...}],
    "serviceSpecification": {...},
    "transportDetails": {...},
    "articleDetails": [{...}]
}

Property	Type	Mandatory	Description
insurance	Insurance	O	Insurance details
references	Array[TransportOrderReference]	O	Shipment references
paymentDefinition	PaymentDefinition	O	Payment details
transportDetails	TransportDetails	O	Additional transport details
serviceSpecification	ServiceSpecification	O	Additional transport services
articleDetails	Array[ArticleDetail]	O	Additional article details

TransportDetails

JSON XML

"...": {
  "oceanCarrier": {...},
  "carrierBookingNumber": "string",
  "carrierContractNumber": "string",
  "hawb": "string",
  "hbl": "string",
  "mawb": "string",
  "mbl": "string",
  "plateNumbers": ["string"],
  "vesselName": "string",
  "voyageNumber": "string"
}

Property	Type	Mandatory	Description
oceanCarrier	OceanCarrier	C	Provide for designated carrier. Mandatory for SEA event tracking.
carrierContractNumber	String	O
carrierBookingNumber	String	O	Mandatory for SEA event tracking (Please note that only one of the values mbl OR carrierBookingNumber is needed).
mbl	String	C	Master-BoL number. Mandatory for SEA event tracking (Please note that only one of the values mbl OR carrierBookingNumber is needed).
hbl	String	O	House-BoL number.
mawb	String	O	Master-AWB number.
hawb	String	O	House-AWB number.
vesselName	String	O	Name of carrier vessel.
voyageNumber	String	O	Vessel voyage number.
plateNumbers	Array String	O	Truck plate numbers.

ArticleDetail

JSON XML

"...": {
  "externalReference": "string",
  "articleCode": "string",
  "description": "string",
  "packageType": {...},
  "referenceNumber1": "string",
  "referenceNumber2": "string",
  "referenceNumber3": "string",
  "hsCode": "string",
  "containerNumber": "string",
  "dimensions": {...},
  "pieces": "number",
  "weight": "number",
  "netWeight": "number",
  "totalVolume": "number",
  "loadingDeviceType": "string",
  "loadingDeviceNumber": "number",
  "quantityPerLoadingDevice": "number",
  "dateOfIssue": {...},
  "expirationDate": {...}
}

Property	Type	Mandatory	Description
externalReference	String	M	External reference. Required for proper correlation.
articleCode	String	O	Article code.
description	String	O	Article description.
packageType	ArticlePackageType	O	Article package type.
referenceNumber1	String	O	Reference number 1.
referenceNumber2	String	O	Reference number 2.
referenceNumber3	String	O	Reference number 3.
hsCode	String	O	Standardized code for classification of commodities.
containerNumber	String	O	Container number. Applicable for `SEA` modality.
dimensions	ArticleDimensions	O	Article dimensions.
pieces	Integer	O	Number of pieces.
weight	BigDecimal	O	Article weight.
netWeight	BigDecimal	O	Article net weight (without packaging).
totalVolume	BigDecimal	O	Total article volume.
loadingDeviceType	String	O	Loading device type.
loadingDeviceNumber	Integer	O	Loading device number.
quantityPerLoadingDevice	Integer	O	Quantity per loading device.
dateOfIssue	ApiDate	O	Issue date.
expirationDate	ApiDate	O	Expiration date.

ArticlePackageType

JSON XML

"...": {
  "unitName": "string",
}

Property	Type	Mandatory	Description
unitName	String	O	SPOT package type code (Package type code list)

ArticleDimensions

JSON XML

"...": {
  "length": "number",
  "width": "number",
  "height": "number",
  "volume": "number"
}

Property	Type	Mandatory	Description
length	String	O	Article length.
width	String	O	Article width.
height	String	O	Article height.
volume	String	O	Article volume.

RoutingInformation

JSON XML

"...": {
	"pickup": {...},
	"delivery": {...},
	"airportOfDeparture": {...},
	"airportOfArrival": {...},
	"portOfLoading": {...},
	"portOfDischarge": {...}
}

Property	Type	Mandatory	Description
pickup	RoutingPickup	M	Information to pickup
delivery	RoutingDelivery	O	Information to delivery
airportOfDeparture	RoutingPointAirport	O
airportOfArrival	RoutingPointAirport	O
portOfLoading	RoutingPointSeaport	O
portOfDischarge	RoutingPointSeaport	O

RoutingPickup

JSON XML

"...": {
  "desiredPickup": {...},
  "estimatedCargoReadiness": {...},
  "estimatedPickup": {...},
  "remark": "string",
  "shipperSelfDelivery": false
}

Property	Type	Mandatory	Description
estimatedCargoReadiness	ApiDate	M	Defines date when goods are ready for transport
desiredPickup	ApiDateFromTo	O	Defines time frame of desired pickup of goods.
estimatedPickup	ApiDate	O	Defines date for estimated pickup of goods. Only processed if EDI-Partner is an Agent or shipperSelfDelivery = true.
shipperSelfDelivery	Boolean	O
remark	String	O	Additional comments for pickup.

RoutingDelivery

JSON XML

"...": {
	"desiredDelivery": {...},
	"estimatedDelivery": {...},
	"consigneeSelfPickup": false,
	"remark": "string"
}

Property	Type	Mandatory	Description
consigneeSelfPickup	Boolean	O
desiredDelivery	ApiDateFromTo	O	Defines time frame of desired delivery of goods.
estimatedDelivery	ApiDate	O	Defines date for estimated delivery of goods. Only processed if EDI-Partner is an Agent or consigneeSelfPickup = true.
remark	String	O	Additional comments for delivery.

RoutingPointAirport

JSON XML

"...": {
	"iataCode":"string",
    "estimatedDate":{...}
 }

Property	Type	Mandatory	Description
iataCode	String	M	IATA 3-letter airport code.
estimatedDate	ApiDate	O	If known, estimated arrival date (if airportOfArrival) / estimated departure date (if airportOfDeparture) can be provided here.

RoutingPointSeaport

JSON XML

"...": {
    "estimatedDate":{...},     
    "terminal":"string",
    "unlocode":"string" 
}

Property	Type	Mandatory	Description
estimatedDate	ApiDate	O	If known, estimated arrival date (if portOfDischarge) / estimated departure date (if portOfLoading) can be provided here.
terminal	String	O	Container terminal.
unlocode	String	M	UNLOCODE 5-letter location code.

Participants

JSON XML

"...": {
    "consignee": {...},
    "controllingAgent": {...},
    "delivery": {...},
    "destinationAgent": {...},
    "destinationHub": {...},
    "destinationWarehouse": {...},
    "exportCustomsBroker": {...},
    "importCustomsBroker": {...},
    "mainInvoiceTo": {...},
    "officeInCharge": {...},
    "originAgent": {...},
    "originHub": {...},
    "originWarehouse": {...},
    "pickup": {...},
    "principal": {...},
    "shipper": {...},
    "shippersTradingCompany": {...},
    "notifyAgent":{...},
    "thirdParties": [...]
}

Property	Type	Mandatory	Description
shipper	Party	M	Party providing the goods.
consignee	Party	M	Party receiving the goods.
pickup	Party	O	Pickup location. If not provided, it will be assumed to be the same as shipper.
delivery	Party	O	Delivery location. If not provided, it will be assumed to be the same as consignee.
principal	Party	M	Owner of the transport order.
officeInCharge	PartyOfficeInCharge	M	Freight forwarder handling office.
mainInvoiceTo	Party	M	Party which will be billed for transport. Is normally the same as the principal.
exportCustomsBroker	Party	O
importCustomsBroker	Party	O
originWarehouse	Party	O
destinationWarehouse	Party	O
shippersTradingCompany	Party	O
notifyAgent	Party	O
thirdParties	Array[Party]	O
originAgent	PartyAgent	O	Not available if `mainModality` is `ROAD`.
destinationAgent	PartyAgent	O	Not available if `mainModality` is `ROAD`.
originHub	PartyAgent	O	Only applicable if `mainModality` is `ROAD`.
destinationHub	PartyAgent	O	Only applicable if `mainModality` is `ROAD`.
controllingAgent	PartyAgent	O

💡

To following parties are only available for agents:

originAgent
destinationAgent
originHub
destinationHub
controllingAgent

PartyAgent

JSON XML

"...": {
  "accountNumber": "string",
  "contacts": [{...}],
  "externalPartyIdentifier": "string",
}

Property	Type	Mandatory	Description
accountNumber	String	M	SPOT internal account number.
externalPartyIdentifier	String	O	EDI-Partners identifier for a party. If provided it functions in the same way as the `accountNumber`
contacts	Array[Contact]	O

PartyOfficeInCharge

JSON XML

layout.tsx / page.tsx

"...": {
	"accountNumber": "123456",
	"officeRole": "string",
	"externalPartyIdentifier": "string",
	"contacts": [{...}]
}

Property	Type	Mandatory	Description
accountNumber	String	M	SPOT internal account number.
officeRole	String	O	Valid values: `ORIGIN_AGENT, DESTINATION_AGENT, CONTROLLING_AGENT`
externalPartyIdentifier	String	O	EDI-Partners identifier for a party. If provided it functions in the same way as the `accountNumber`
contacts	Array[Contact]	O

💡

The field officeRole is only available for agents. If you are not classified as an agent or the field is left empty, the role will be calculated based on the value of businessDirection

OrderComment

JSON XML

"...": {
    "permissions":{
      "permissions_val":"string"
    },
    "text":"string"
}

Property	Type	Mandatory	Description
permissions	array [permissions]	M	permissions
text	string	M	text field for order comment

permissions

Property	Type	Mandatory	Description
permissions_val	string	M	Valid values: `SHIPPER, PICKUP, CONSIGNEE, DELIVERY, PRINCIPAL, MAIN_INVOICE_TO, CONTROLLING_AGENT, OFFICE_IN_CHARGE, ORIGIN_AGENT, ORIGIN_HUB, TRANSIT_HUB, EXPORT_CONSOLIDATION_HUB, IMPORT_DECONSOLIDATION_HUB, SEA_HUB, AIR_HUB, DESTINATION_AGENT, DESTINATION_HUB, NOTIFY_AGENT, SHIPPERS_TRADING_COMPANY, EXPORT_CUSTOMS_BROKER, IMPORT_CUSTOMS_BROKER, ORIGIN_WAREHOUSE, DESTINATION_WAREHOUSE, THIRD_PARTY, ROAD_CARRIER`

General Rules Shipment Event