Transport Common Objects - EDI Portal Spotworx

CargoDescription

"...": {
    "containerIndex": 1,
    "cargoDetails": [{...}],
    "chargeableWeight": 0,
    "currencyCode": "string",
    "dangerousGoods": [{...}],
    "loadingMeters": 0,
    "valueOfGoods": 0,
    "ssccNumbers": [
        "310000001000000014",
        "310000001000000026"
    ]
}

Property	Type	Mandatory	Description
containerIndex	Integer	O	Running number for association with container
cargoDetails	Array[CargoDetails]	M
valueOfGoods	BigDecimal	O
currencyCode	String	C	ISO 4217 three letter currency code. Mandatory if `valueOfGoods` is provided
chargeableWeight	BigDecimal	O
loadingMeters	BigDecimal	O
dangerousGoods	Array[DangerousGoods]	O
ssccNumbers	Array[String]	O	Array of ssccNumbers

CargoDetails

JSON XML

"...": {
	"description": "string",
	"height": 0,
	"length": 0,
	"packageTypeCode": "string",
	"pieces": 0,
	"volume": 0,
	"weight": 0,
	"width": 0
 }

Property	Type	Mandatory	Description
pieces	Integer	M
packageTypeCode	String	M	SPOT package type code (Package type code list)
description	String	M
weight	BigDecimal	O	Weight in kg
width	Integer	O	Width in cm
height	Integer	O	Height in cm
length	Integer	O	Length in cm
volume	BigDecimal	O	Volume in m³. Will only be taken over if no dimensions are provided. If dimensions are provided, volume will be automatically calculated.

Contact

JSON XML

"...": {
  "emailBusiness": "string",
  "emailOther": "string",
  "externalReference": "string",
  "fax": {...},
  "firstName": "string",
  "jobRole": "string",
  "jobTitle": "string",
  "lastName": "string",
  "mobile": {...},
  "phoneBusiness": {...},
  "phoneOther": {...},
  "salutation": "MR",
  "title": "string"
}

Property	Type	Mandatory	Description
salutation	String	M	Valid values: `MR, MS`
title	String	O
firstName	String	M
lastName	String	M
jobTitle	String	O
jobRole	String	O
phoneBusiness	Phone	O	Contact business phone number.
phoneOther	Phone	O	Additional phone number.
mobile	Phone	O	Contact mobile phone number.
fax	Phone	O	Contact fax number.
emailBusiness	String	O	Contact business email address.
emailOther	String	O	Additional email address.

ContainerDefinition

JSON XML

"...": {
    "containers": [{...}],
    "currencyCode": "string",
    "generalCargoDescription": "string",
    "goodsValue": 0,
    "totalPieces": 0,
    "totalVolume": 0,
    "totalWeight": 0
}

Property	Type	Mandatory	Description
containers	Array[Container]	M	Specify details per container.
generalCargoDescription	String	M
goodsValue	BigDecimal	O	Value of goods in all containers.
currencyCode	String	C	ISO 4217 three letter currency code. Mandatory if `goodsValue` is provided.
totalPieces	Integer	O	Overall pieces of goods.
totalVolume	BigDecimal	O	Overall volume of goods.
totalWeight	BigDecimal	O	Overall weight of goods.

Container

JSON XML

"...": {
    "containerIndex": 0,
    "containerNumber": "",
    "containerCode": "",
    "sealNumber": "",
    "atbNumber": "",
    "references": [{...}],
    "additionalAttributes": [...]
}

Property	Type	Mandatory	Description
containerIndex	Integer	M	Running number identifying a container.
containerNumber	String	C	ISO 6346 container number. Required when container references are provided.
containerCode	String	C	ISO 6346 Standard Container Code. Mandatory for SEA FCL. e.g. 22GP, 22G1, 42GP, 42UT, L5BK ...
sealNumber	String	O
atbNumber	String	O
references	Array[TransportOrderReference]	O	References on container level
additionalAttributes	Array[String]	O	Garments on hanger: `GOH`, Non-operated reefer: `ROH`, Shippers own container: `SOC`

Event

JSON XML

"...": {
	"eventTypeIdentifier": "string",
	"eventTypeName": "string",
	"eventTimestamp": {...},
	"remark": "string",
	"containerNumber": "string",
	"eventLocation": {...},
	"additionalAttributes": [{...}]
}

Property	Type	Mandatory	Description
eventTypeIdentifier	String	M	Identifier of eventType. (Event type list)
eventTypeName	String	M	Full name of the event.
eventTimestamp	ApiDate	M	Date of event occurrence.
eventLocation	EventLocation	M	Location of event occurrence.
remark	String	O	A remark to the event.
additionalAttributes	Array[EventAdditionalAttribute]	C	Array of additional attributes to an event.
containerNumber	String	O	ISO 6346 container number. If provided, event will only be set on this container.

💡

The field containerNumber is only applicable for shipments of the type: SEA.

The below described list provides an overview about the main event types.

The full list of all event types can be found here.

Identifier	Type	Description
84	REAL	Order confirmation
13	ESTIMATED	Estimated cargo readiness
15	REAL	Cargo ready
9	REAL	PICKED UP
5	ESTIMATED	Estimated departure
7	REAL	DEPARTED
21	REAL	PreAlert processed
1	ESTIMATED	Estimated arrival
4	REAL	ARRIVED
10	ESTIMATED	Estimated delivery
12	REAL	DELIVERED

EventLocation

JSON XML

"...": {
    "locationType": "string",
    "unlocodeLocation": {...},
    "iataLocation": {...},
    "addressLocation": {...},
    "freeLocation": {...},
    "rpType": "string"
}

This defines the location of the event occurrence. Depending on the value of locationType, the corresponding object needs to be provided.

Property	Type	Mandatory	Description
locationType	String	M	type identifier of the location `UNLOCODE, IATA, ADDRESS, FREE`.
unlocodeLocation	EventUnlocodeLocation	C	location of type UNLOCODE.
iataLocation	EventIataLocation	C	location of type IATA.
addressLocation	EventAddressLocation	C	location of type ADDRESS.
freeLocation	EventFreeLocation	C	location of type FREE.
rpType	String	C	routing point type. Valid values: PICKUP, PLACE_OF_RECEIPT, EXPORT_CONSOLIDATION_HUB, ORIGIN_WAREHOUSE, DEPARTURE_AIRPORT, PORT_OF_LOADING, LOADING_TERMINAL, TRANSIT_HUB, ORIGIN_HUB, SEA_HUB, RAIL_HUB, AIR_HUB, DESTINATION_HUB, ARRIVAL_AIRPORT, PORT_OF_DISCHARGE, DISCHARGE_TERMINAL, IMPORT_DECONSOLIDATION_HUB, DESTINATION_WAREHOUSE, FINAL_DESTINATION, PLACE_OF_HANDOVER, DELIVERY, UNASSIGNED_HUB

EventUnlocodeLocation

JSON XML

"...": {
	"unlocode": "string"
}

Property	Type	Mandatory	Description
unlocode	String	M	UNLOCODE 5-letter location code.

EventIataLocation

JSON XML

"...": {
	"iataCode": "string"
}

Property	Type	Mandatory	Description
iataCode	String	M	IATA 3-letter airport code.

EventAddressLocation

JSON XML

"...": {
	"city": "string",
	"street": "string",
	"postCode": "string",
	"countryCode": "string"
}

Property	Type	Mandatory	Description
city	String	M	Name of the city/location.
street	String	O	Street address part (including house, store, door numbers).
postCode	String	O	postal code of the city/location.
countryCode	String	M	ISO country code (ISO 3166-1 Alpha-2).

EventFreeLocation

JSON XML

"...": {
	"name": "string"
}

Property	Type	Mandatory	Description
name	String	M	any free-text location information.

EventAdditionalAttribute

JSON XML

"...": [{
	"identifier": "string",
	"value": "string"
}]

Some events have additional attributes e.g.: DELIVERED has an attribute POD Name, which gives information about who accepted the delivery. Please see attached excel sheet for detailed identifiers and events.

Property	Type	Mandatory	Description
identifier	String	M	Identifier of attribute. (Additional attributes list)
value	String	M	Attribute value

Insurance

JSON XML

"...": {
	"currencyCode": "string",
	"requiredBy": "CONSIGNEE",
	"value": 0
}

Property	Type	Mandatory	Description
value	BigDecimal	O	Insurance value.
currencyCode	String	C	ISO 4217 three letter currency code. Mandatory if value is provided.
requiredBy	String	O	party/contact who requires insurance, if applicable. Valid values: `SHIPPER, CONSIGNEE, PRINCIPAL`

OceanCarrier

JSON XML

"...": {
    "name": "string",
    "scac": "string"
}

Property	Type	Mandatory	Description
scac	String	M	SCAC of carrier.
name	String	O	Name of carrier.

Party

JSON XML

"...": {
  "accountNumber": "string",
  "partyId": 123456,
  "city": "string",
  "contacts": [{...}],
  "countryCode": "string",
  "email": "string",
  "externalPartyIdentifier": "string",
  "externalReference": "string",
  "fax": {...},
  "matchCode": "string",
  "name": "string",
  "otherPhone": {...},
  "phone": {...},
  "state": "string",
  "street": "string",
  "zipCode": "string"
}

Property	Type	Mandatory	Description
accountNumber	String	O	SPOT internal account number. If provided no additional info required.
partyId	Integer	O	Party Identification number
name	String	C	Mandatory if no `accountNumber` or `externalPartyIdentifier` is provided.
externalPartyIdentifier	String	O	EDI-Partners identifier for a party. If provided it functions in the same way as the `accountNumber`
externalReference	String	O
matchCode	String	O
city	String	C	Mandatory if no `accountNumber` or `externalPartyIdentifier` is provided.
street	String	C	Mandatory if no `accountNumber` or `externalPartyIdentifier` is provided.
zipCode	String	O
state	String	O
countryCode	String	C	ISO country code (ISO 3166-1 Alpha-2). Mandatory if no `accountNumber` or `externalPartyIdentifier` is provided.
phone	Phone	O
fax	Phone	O
email	String	O
webSite	String	O
otherPhone	Phone	O
contacts	Array[Contact]	O

PaymentDefinition

JSON XML

"...": {
  "cashOnDelivery": 0,
  "codCurrencyCode": "string",
  "letterOfCredit": "string",
  "termsOfPayment": "CASH_AGAINST_DOCUMENT"
}

Property	Type	Mandatory	Description
termsOfPayment	String	O	Defines the terms of payment. Valid values: `LETTER_OF_CREDIT, OPEN_ACCOUNT, COD, CASH_AGAINST_DOCUMENT, SHIPMENT_RELEASE_AFTER_CONFIRMATION_ONLY, PAID_IN_ADVANCE`
cashOnDelivery	BigDecimal	C	value for Cash-On-Delivery. Mandatory if `termsOfPayment` is set to `COD`
codCurrencyCode	String	C	ISO 4217 three letter currency code. Mandatory if `cashOnDeliveryValue` is provided.
letterOfCreditNumber	String	C	Mandatory if `termsOfDelivery` is set to `LETTER_OF_CREDIT`

ServiceSpecification

JSON XML

"...": {
  "billOfLoadingType": "EMPTY",
  "serviceDefinition": "ECONOMY",
  "specialHandlingClassification": [
    "GARMET_ON_HANGER"
  ],
  "specialHandlingClassificationRoad": [
      "PICKUP_AVISO_REQUIRED",
      "DELIVERY_AVISO_REQUIRED",
      "PICKUP_TIMESLOT_BOOKING_REQUIRED",
      "PALLET_TRADING"
  ],
  "temperatureFrom": 0,
  "temperatureTo": 0
}

Property	Type	Mandatory	Description
billOfLoading	String	O	Valid values: `EMPTY, EXPRESS_BL_REQUIRED, ORIGINAL_BL_REQUIRED, TELEX_RELEASE`
serviceDefinition	String	O	Valid values: `ECONOMY, EXPRESS, EMERGENCY` Default if not provided: `ECONOMY`
specialHandlingClassification	Array[String]	O	Valid values: `GARMET_ON_HANGER, HEAVY_LIFT, HUMIDITY_CONTROLLED, OVERSIZED, ROLL_ON_OFF, TEMPERATURE_CONTROLLED, VALUABLE_CARGO`
specialHandlingClassificationRoad	Array[String]	O	Valid values: `PICKUP_AVISO_REQUIRED, DELIVERY_AVISO_REQUIRED, PICKUP_TIMESLOT_BOOKING_REQUIRED, PALLET_TRADING`
temperatureFrom	Decimal	C	Min. temperature. Mandatory if `specialHandlingClassification` contains `TEMPERATURE_CONTROLLED`
temperatureTo	Decimal	C	Max. temperature. Mandatory if `specialHandlingClassification` contains `TEMPERATURE_CONTROLLED`

TransportDeliveryTerm

JSON XML

"...": {
    "deliveryTerm": "string",
    "deliveryTermLocation": "string",
}

Property	Type	Mandatory	Description
deliveryTerm	String	M	3-letter Incoterms® code. (List of Incoterms®).
deliveryTermLocation	String	M	Location of delivery term.

More information regarding the Incoterms® rules can be found at the Incoterms® rules 2010 (opens in a new tab) page of the International Chamber of Commerce.

"Incoterms" is a trademark of the International Chamber of Commerce.

TransportOrderReference

JSON XML

"...": {
	"referenceType": "string",
	"referenceKey": "string",
	"referenceNumber": "string"
}

Property	Type	Mandatory	Description
referenceType	String	M	Type of reference. (List of SPOT reference types)
referenceKey	String	O	Key for referenceNumber assignment (For example EDI-Partner reference type).
referenceNumber	String	M	Reference value.

Invoice Shipment Data