NAV Navbar
Spot
JSON XML

Introduction

A documentation Platform, made by developers for developers to support the daily business in international freight transports and logistics.

You can use our standard interfaces to get or post transport/logistics data.

The API is only available for registered customers.

Interested in using SPOT or our API? Contact us, it’s free!

General

Message Structure

Structured Files

For easier understanding and implementation there is a default message header in each file. We provide this header in CSV, XML, JSON etc. to provide information about the file transfer itself.

MessageHeader

"messageHeader": {
    "messageId": "1",
    "messageDate": "2017-02-08",
    "messageTime": "11:52:26",
    "messageType": "transport.eventUpdate",
    "messageVersion": "V1.0",
    "messageScope": "TEST"
}
<messageHeader>
    <messageId>244016</messageId>
    <messageDate>2017-04-05</messageDate>
    <messageTime>00:18:06</messageTime>
    <messageType>transport.clientTransportOrder</messageType>
    <messageVersion>1.0</messageVersion>
    <messageScope>PROD</messageScope>
</messageHeader>
Property Type Mandatory Description
messageId String M Identifier for tracing in case of error/debugging.
messageDate String M Date of message transfer in format YYYY-MM-DD as defined by ISO 8601.
messageTime String M UTC Time of message transfer in format hh:mm:ss as defined by ISO 8601.
messageType String M Unique identifier to distinguish between different message types.
messageVersion String M Message version.
messageScope String M Valid values: DEV, TEST, PROD

Transport

Client Transport Orders

CREATE Client Transport Order

messageType: transport.clientTransportOrder

{
    "messageHeader":{...},
    "clientTransportOrder":{...}
}
<?xml version="1.0" encoding="UTF-8" ?>
<clientTransportOrders>
    <messageHeader>...</messageHeader>
    <ClientTransportOrder>...</ClientTransportOrder>
</clientTransportOrders>

Creates a transport order in our SPOT system.

FTP folder: /in/transport/clientTransportOrders

Sample files

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.

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

ClientTransportOrder

"ClientTransportOrder":{
  "businessDirection": "EXPORT",
  "cargoDescription": [{...}],
  "containerDefinition": {...},
  "customerAccountNumber": "string",
  "deliveryTerm": {...},
  "mainCategory": "FCL",
  "mainModality": "AIR",
  "orderDetails": {...},
  "participants": {...},
  "routingInformation": {...}
}
<ClientTransportOrder>
  <businessDirection>EXPORT</businessDirection>
  <cargoDescription>...</cargoDescription>
  <containerDefinition>...</containerDefinition>
  <customerAccountNumber>string</customerAccountNumber>
  <deliveryTerm>...</deliveryTerm>
  <mainCategory>FCL</mainCategory>
  <mainModality>AIR</mainModality>
  <orderDetails>...</orderDetails>
  <participants>...</participants>
  <routingInformation>...</routingInformation>
</ClientTransportOrder>
Property Type Mandatory Description
businessDirection String M Identifies direction of goods from principals viewpoint.
Valid values: IMPORT, EXPORT, TRIANGLE
cargoDescription Array[CargoDescription] M Transport cargo description. For FCL/REEFER per container.
containerDefinition ContainerDefinition C Mandatory for SEA FCL, REEFER
deliveryTerm DeliveryTerm M IncoTerm and Location
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
mainModality String M Modality of transport. Valid values: AIR, ROAD, SEA, AIR_SEA, SEA_AIR
customerAccountNumber String M Your SPOT account number. This is used to associate the created order with your company or office.
orderDetails OrderDetails O Additional detail information
participants Participants M Parties participating in a transport
routingInformation RoutingInformation M Information about the transport routing and dates

OrderDetails

"orderDetails": {
    "insurance": {...},
    "paymentDefinition": {...},
    "references": [{...}],
    "serviceSpecification": {...},
    "transportDetails": {...}
}
  <orderDetails>
    <insurance>...</insurance>
    <paymentDefinition>...</paymentDefinition>
    <references>...</references>
    <serviceSpecification>...</serviceSpecification>
    <transportDetails>...</transportDetails>
  </orderDetails>
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

TransportDetails

"transportDetails": {
  "oceanCarrier": {...},
  "carrierBookingNumber": "string",
  "carrierContractNumber": "string",
  "hawb": "string",
  "hbl": "string",
  "mawb": "string",
  "mbl": "string",
  "plateNumber": "string",
  "vesselName": "string",
  "voyageNumber": "string"
}
<transportDetails>
  <oceanCarrier>...</oceanCarrier>
  <carrierBookingNumber>string</carrierBookingNumber>
  <carrierContractNumber>string</carrierContractNumber>
  <hawb>string</hawb>
  <hbl>string</hbl>
  <mawb>string</mawb>
  <mbl>string</mbl>
  <plateNumber>string</plateNumber>
  <vesselName>string</vesselName>
  <voyageNumber>string</voyageNumber>
</transportDetails>
Property Type Mandatory Description
oceanCarrier OceanCarrier O Provide for designated carrier.
carrierContractNumber String O
carrierBookingNumber String O
mbl String O Master-BoL number.
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.

RoutingInformation

"routingInformation":{
    "pickup":{...},
    "delivery":{...},
    "airportOfDeparture":{...},
    "airportOfArrival":{...},
    "portOfLoading":{...},
    "portOfDischarge":{...}
}
<routingInformation>
    <airportOfArrival>...</airportOfArrival>
    <airportOfDeparture>...</airportOfDeparture>
    <delivery>...</delivery>
    <pickup>...</pickup>
    <portOfDischarge>... </portOfDischarge>
    <portOfLoading>...</portOfLoading>
</routingInformation>
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

"pickup": {
  "desiredPickup": {...},
  "estimatedCargoReadiness": {...},
  "estimatedPickup": {...},
  "remark": "string",
  "shipperSelfDelivery": false
}
<pickup>
  <desiredPickup>...</desiredPickup>
  <estimatedCargoReadiness>...</estimatedCargoReadiness>
  <estimatedPickup>...</estimatedPickup>
  <remark>string</remark>
  <shipperSelfDelivery>false</shipperSelfDelivery>
</pickup>
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

"delivery":{
    "desiredDelivery":{...},
    "estimatedDelivery":{...},
    "consigneeSelfPickup": false,
    "remark":"string"
}
<delivery>
    <consigneeSelfPickup>false</consigneeSelfPickup>
    <desiredDelivery>...</desiredDelivery>
    <estimatedDelivery>...</estimatedDelivery>
    <remark>string</remark>
</delivery>
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

"airportOfDeparture":{
    "iataCode":"string",
    "estimatedDate":{...}
 }
<airportOfDeparture>
  <estimatedDate>...</estimatedDate>
  <iataCode>string</iataCode>
</airportOfDeparture>

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

"portOfLoading":{
    "estimatedDate":{...},     
    "terminal":"string",
    "unlocode":"string" 
}
<portOfLoading>
  <estimatedDate>...</estimatedDate>
  <terminal>string</terminal>
  <unlocode>string</unlocode>
</portOfLoading>
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

"participants": {
    "consignee": {...},
    "controllingAgent": {...},
    "delivery": {...},
    "destinationAgent": {...},
    "destinationHub": {...},
    "destinationWarehouse": {...},
    "exportCustomsBroker": {...},
    "importCustomsBroker": {...},
    "mainInvoiceTo": {...},
    "notifyAgent": {...},
    "officeInCharge": {...},
    "originAgent": {...},
    "originHub": {...},
    "originWarehouse": {...},
    "pickup": {...},
    "principal": {...},
    "shipper": {...},
    "shippersTradingCompany": {...},
    "thirdParties": [...]
}
<participants>
    <consignee>...</consignee>
    <controllingAgent>...</controllingAgent>
    <delivery>...</delivery>
    <destinationAgent>...</destinationAgent>
    <destinationHub>...</destinationHub>
    <destinationWarehouse>...</destinationWarehouse>
    <exportCustomsBroker>...</exportCustomsBroker>
    <importCustomsBroker>...</importCustomsBroker>
    <mainInvoiceTo>...</mainInvoiceTo>
    <notifyAgent>...</notifyAgent>
    <officeInCharge>...</officeInCharge>
    <originAgent>...</originAgent>
    <originHub>...</originHub>
    <originWarehouse>...</originWarehouse>
    <pickup>...</pickup>
    <principal>...</principal>
    <shipper>...</shipper>
    <shippersTradingCompany>...</shippersTradingCompany>
    <thirdParties>...</thirdParties>
</participants>
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
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
notifyAgent PartyAgent O

PartyAgent

"controllingAgent": {
  "accountNumber": "string",
  "contacts": [{...}],
  "externalPartyIdentifier": "string",
}
<controllingAgent>
    <accountNumber>string</accountNumber>
    <contacts>...</contacts>
    <externalPartyIdentifier>string</externalPartyIdentifier>
</controllingAgent>
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

"officeInCharge": {
    "accountNumber": "123456",
    "officeRole":"string",
    "externalPartyIdentifier":"string",
    "contacts":[{...}]
}
<officeInCharge>
  <accountNumber>string</accountNumber>
  <contacts>...</contacts>
  <externalPartyIdentifier>string</externalPartyIdentifier>
  <officeRole>CONTROLLING_AGENT</officeRole>
</officeInCharge>
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

Shipments

GET Shipment

messageType: transport.shipment

{
    "messageHeader":{...},
    "Shipment":{...}
}
<?xml version="1.0" encoding="UTF-8" ?>
<shipments>
    <messageHeader>...</messageHeader>
    <Shipment>...</Shipment>
</shipments>

Get shipment data from SPOT.

FTP folder if provided on our FTP and not pushed to partner FTP: /out/transport/shipments

Sample files: XML

The sample files provided are based on real world shipments where parties and references have been changed for privacy reasons.

You can also get into contact with our Integration Competence Center and we will provide you with real examples based on your shipments.

Property Type Mandatory Description
messageHeader MessageHeader M Message Header information.
Shipment Shipment M Shipment information

Shipment

{
  "cargoDescription": [{...}],
  "containerDefinition": {...},
  "events": [{...}],
  "mainCategory": "FCL",
  "mainModality": "AIR",
  "participants": {...},
  "routingInformation": [{...}],
  "shipmentDetails": {...},
  "trackingId": "string"
}
<Shipment>
  <cargoDescription>...</cargoDescription>
  <containerDefinition>...</containerDefinition>
  <events>...</events>
  <mainCategory>FCL</mainCategory>
  <mainModality>AIR</mainModality>
  <participants>...</participants>
  <routingInformation>...</routingInformation>
  <shipmentDetails>...  </shipmentDetails>
  <trackingId>string</trackingId>
</Shipment>
Property Type Mandatory Description
cargoDescription Array[CargoDescription] M Transport cargo description. For FCL/REEFER per container.
containerDefinition ContainerDefinition C Available for SEA FCL/REEFER.
events Array[Event] M List of transport events
mainCategory String C Valid values for ROAD: FTL, LTL, GROUPAGE
Valid values for SEA: FCL, LCL, REEFER. Not available for AIR
mainModality String M Modality of transport. Values: AIR, ROAD, SEA, AIR_SEA, SEA_AIR
participants ShipmentParticipants M Parties participating in a transport
routingInformation ShipmentRoutingInformation M Information about shipment routing
shipmentDetails ShipmentDetails M Additional shipment details
trackingId String M SPOT Shipment tracking ID. (SPOT ID)

ShipmentParticipants

"participants": {
    "airHub": {...},
    "consignee": {...},
    "controllingAgent": {...},
    "delivery": {...},
    "destinationAgent": {...},
    "destinationHub": {...},
    "destinationWarehouse": {...},
    "exportCustomsBroker": {...},
    "exportConsolidationHub": {...},
    "importCustomsBroker": {...},
    "exportDeconsolidationHub": {...},
    "mainInvoiceTo": {...},
    "notifyAgent": {...},
    "originAgent": {...},
    "originHub": {...},
    "originWarehouse": {...},
    "pickup": {...},
    "principal": {...},
    "seaHub": {...},
    "shipper": {...},
    "shippersTradingCompany": {...},
    "thirdParties": [{...}],
    "transitHubs": [{...}]
}
<participants>
    <airHub>...</airHub>
    <consignee>...</consignee>
    <controllingAgent>...</controllingAgent>
    <delivery>...</delivery>
    <destinationAgent>...</destinationAgent>
    <destinationHub>...</destinationHub>
    <destinationWarehouse>...</destinationWarehouse>
    <exportCustomsBroker>...</exportCustomsBroker>
    <exportConsolidationHub>...</exportConsolidationHub>
    <importCustomsBroker>...</importCustomsBroker>
    <importDeconsolidationHub>...</importDeconsolidationHub>
    <mainInvoiceTo>...</mainInvoiceTo>
    <notifyAgent>...</notifyAgent>
    <originAgent>...</originAgent>
    <originHub>...</originHub>
    <originWarehouse>...</originWarehouse>
    <pickup>...</pickup>
    <principal>...</principal>
    <seaHub>...</seaHub>
    <shipper>...</shipper>
    <shippersTradingCompany>...</shippersTradingCompany>
    <thirdParties>...</thirdParties>
    <transitHubs>...</transitHubs>
</participants>
Property Type Mandatory Description
airHub Party O
consignee Party M
controllingAgent Party M Office in charge of transport.
delivery Party C Delivery location. Not available if shipperSelfDelivery is true.
destinationAgent Party O Not available if mainModality is ROAD.
destinationHub Party C Only available if mainModality is ROAD and mainCategory is GROUPAGE.
destinationWarehouse Party O
exportCustomsBroker Party O
exportConsolidationHub Party O
importCustomsBroker Party O
importDeconsolidationHub Party O
mainInvoiceTo Party M Party which will be invoiced.
notifyAgent Party O
originAgent Party O Not available if mainModality is ROAD.
originHub Party C Only available if mainModality is ROAD and mainCategory is GROUPAGE.
originWarehouse Party O
pickup Party C Pickup location. Not available if consigneeSelfPickup is true.
principal Party M Owner of the transport order.
seaHub Party O
shipper Party M
shippersTradingCompany Party O
thirdParties Array[Party] O
transitHubs Array[Party] O

ShipmentRoutingInformation

"routingInformation": {
    "delivery": {...},
    "pickup": {...},
    "routingPoints": [{...}]
}
<routingInformation>
    <delivery>...</delivery>
    <pickup>...</pickup>
    <routingPoints>...</routingPoints>
</routingInformation>
Property Type Mandatory Description
pickup ShipmentRoutingPointPickup M Information to pickup
routingPoints Array[ShipmentRoutingPoint] O Information to routing points between Pickup and Delivery (e.g. Port of loading, Port of discharge, …)
delivery ShipmentRoutingPointDelivery M Information to delivery

ShipmentRoutingPoint

"routingPoints": [{
    "city": "string",
    "countryCode": "string",
    "estimatedArrival": {...},
    "estimatedDeparture": {...},
    "iataCode": "string",
    "legModality": "SEA_FCL",
    "realArrival": {...},
    "realDeparture": {...},
    "remark": "string",
    "routingPointType": "PICKUP",
    "unlocode": "string",
    "zipCode": "string"
}]
<routingPoints>
  <city>string</city>
  <countryCode>string</countryCode>
  <estimatedArrival>...</estimatedArrival>
  <estimatedDeparture>...</estimatedDeparture>
  <iataCode>string</iataCode>
  <legModality>SEA_FCL</legModality>
  <realArrival>...</realArrival>
  <realDeparture>...</realDeparture>
  <remark>string</remark>
  <routingPointType>PICKUP</routingPointType>
  <unlocode>string</unlocode>
  <zipCode>string</zipCode>
</routingPoints>
Property Type Mandatory Description
remark String O
routingPointType String M Valid values: EXPORT_CONSOLIDATION_HUB, ORIGIN_WAREHOUSE, DEPARTURE_AIRPORT, PORT_OF_LOADING, TRANSIT_HUB, ORIGIN_HUB, SEA_HUB, AIR_HUB, DESTINATION_HUB, ARRIVAL_AIRPORT, PORT_OF_DISCHARGE, IMPORT_DECONSOLIDATION_HUB, DESTINATION_WAREHOUSE, FINAL_DESTINATION, UNASSIGNED_HUB
legModality String O If specified, shows transport modality between this and the next routing point.
countryCode String C Routing point location ISO country code (ISO 3166-1 Alpha-2)
city String C Routing point location city
zipCode String C Routing point location zipCode
iataCode String C 3-letter IATA location code of routing point.
unlocode String C 5-letter UnLocode location of routing point.
estimatedArrival ApiDate O Estimated arrival at specified routing location.
realArrival ApiDate O Actual arrival at specified routing location.
estimatedDeparture ApiDate O Estimated departure from specified routing location.
realDeparture ApiDate O Actual departure from specified routing location.

ShipmentRoutingPointPickup

"pickup": {
  "city": "string",
  "countryCode": "string",
  "desiredPickup": {...},
  "estimatedCargoReadiness": {...},
  "estimatedPickup": {...},
  "iataCode": "string",
  "legModality": "SEA_FCL",
  "realCargoReadiness": {...},
  "realPickup": {...},
  "remark": "string",
  "routingPointType": "PICKUP",
  "shipperSelfDelivery": true,
  "unlocode": "string",
  "zipCode": "string"
}
<pickup>
  <city>string</city>
  <countryCode>string</countryCode>
  <desiredPickup>...</desiredPickup>
  <estimatedCargoReadiness>...</estimatedCargoReadiness>
  <estimatedPickup>...</estimatedPickup>
  <iataCode>string</iataCode>
  <legModality>SEA_FCL</legModality>
  <realCargoReadiness>...</realCargoReadiness>
  <realPickup>...</realPickup>
  <remark>string</remark>
  <routingPointType>PICKUP</routingPointType>
  <shipperSelfDelivery>true</shipperSelfDelivery>
  <unlocode>string</unlocode>
  <zipCode>string</zipCode>
</pickup>
Property Type Mandatory Description
remark String O
routingPointType String M Valid values: PICKUP, PLACE_OF_RECEIPT
legModality String O If specified, shows transport modality between this and the next routing point.
countryCode String C Routing point location ISO country code (ISO 3166-1 Alpha-2)
city String C Routing point location city
zipCode String O Routing point location zipCode
iataCode String C 3-letter IATA location code of routing point.
unlocode String C 5-letter UnLocode location of routing point.
estimatedCargoReadiness ApiDate M Estimated date when cargo will be ready for transport.
realCargoReadiness ApiDate O Actual date when cargo was ready for transport.
estimatedPickup ApiDate O Estimated date when cargo will be picked up.
realPickup ApiDate O Actual date when cargo was picked up.
desiredPickup ApiDateFromTo O Time frame of desired pickup of cargo.
shipperSelfDelivery Boolean O

ShipmentRoutingPointDelivery

"delivery": {
  "city": "string",
  "consigneeSelfPickup": true,
  "countryCode": "string",
  "desiredDelivery": {...},
  "estimatedDelivery": {...},
  "iataCode": "string",
  "legModality": "SEA_FCL",
  "realDelivery": {...},
  "remark": "string",
  "routingPointType": "PICKUP",
  "unlocode": "string",
  "zipCode": "string"
}
<delivery>
  <city>string</city>
  <consigneeSelfPickup>true</consigneeSelfPickup>
  <countryCode>string</countryCode>
  <desiredDelivery>...</desiredDelivery>
  <estimatedDelivery>...</estimatedDelivery>
  <iataCode>string</iataCode>
  <legModality>SEA_FCL</legModality>
  <realDelivery>...</realDelivery>
  <remark>string</remark>
  <routingPointType>PICKUP</routingPointType>
  <unlocode>string</unlocode>
  <zipCode>string</zipCode>
</delivery>
Property Type Mandatory Description
remark String O
routingPointType String M Valid values: PLACE_OF_HANDOVER, DELIVERY
legModality String O If specified, shows transport modality between this and the next routing point.
countryCode String C Routing point location ISO country code (ISO 3166-1 Alpha-2)
city String C Routing point location city
zipCode String C Routing point location zipCode
iataCode String C 3-letter IATA location code of routing point.
unlocode String C 5-letter UnLocode location of routing point.
consigneeSelfPickup Boolean O
estimatedDelivery ApiDate O Estimated date when cargo will be delivered.
realDelivery ApiDate O Actual date when cargo was delivered.
desiredDelivery ApiDate O Time frame of desired delivery of cargo.

ShipmentDetails

"shipmentDetails": {
    "deliveryTerm": {...},
    "electronicFreight": "string",
    "hblOriginalRequired": true,
    "insurance": {...},
    "paymentDefinition": {...},
    "references": [{...}],
    "serviceSpecification": {...},
    "shipmentTransportDetails": {...}
}
<shipmentDetails>
    <deliveryTerm>...</deliveryTerm>
    <electronicFreight>string</electronicFreight>
    <hblOriginalRequired>true</hblOriginalRequired>
    <insurance>...</insurance>
    <paymentDefinition>...</paymentDefinition>
    <references>...</references>
    <serviceSpecification>...</serviceSpecification>
    <shipmentTransportDetails>...</shipmentTransportDetails>
</shipmentDetails>
Property Type Mandatory Description
deliveryTerm DeliveryTerm M IncoTerm and Location
electronicFreight String O
hblOriginalRequired Boolean O
insurance Insurance O Insurance details
paymentDefinition PaymentDefinition O Payment information
references Array[TransportOrderReference] O Shipment references
serviceSpecification ServiceSpecification O Additional transport services
shipmentTransportDetails ShipmentTransportDetails O Additional transport details

ShipmentTransportDetails

"shipmentTransportDetails": {
  "carrierContractNumber": "string",
  "flightNumbers": ["string"],
  "hawb": "string",
  "hbl": "string",
  "mawb": "string",
  "mbl": "string",
  "oceanCarrier": {...},
  "plateNumbers": ["string"],
  "roadCarrier": "string",
  "vesselName": "string",
  "voyageNumber": "string"
}
<shipmentTransportDetails>
  <carrierContractNumber>string</carrierContractNumber>
  <flightNumbers>string</flightNumbers>
  <hawb>string</hawb>
  <hbl>string</hbl>
  <mawb>string</mawb>
  <mbl>string</mbl>
  <oceanCarrier>...</oceanCarrier>
  <plateNumbers>string</plateNumbers>
  <roadCarrier>string</roadCarrier>
  <vesselName>string</vesselName>
  <voyageNumber>string</voyageNumber>
</shipmentTransportDetails>
Property Type Mandatory Description
carrierContractNumber String O
flightNumbers Array[String] O
mbl String O Master-BoL number
hbl String O House-BoL number
mawb String O Master-AWB number
hawb String O House-AWB number
oceanCarrier OceanCarrier O Information about ocean carrier
plateNumbers Array[String] O Truck plate numbers
roadCarrier String O Name of road carrier
vesselName String O Name of carrier vessel
voyageNumber String O Vessel voyage number

Shipment Events

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

Shipment Event Updates

POST/GET Event update

messageType: transport.eventUpdate

{
    "messageHeader": {...},
    "trackingId": "string",
    "transportReferences": [{...}],
    "references": [{...}],
    "events": [{...}]
}
<eventUpdate>
    <messageHeader>...</messageHeader>
    <trackingId>string</trackingId>
    <transportReferences>...</transportReferences>
    <references>...</references>
    <events>...</events>
</eventUpdate>

This is used to either create events in our SPOT system or to receive event information when events are updated on your shipment.

Sample files: XML

FTP folder:

For inbound event updates: /in/transport/eventUpdates

For outbound event updates, if provided on our FTP and not pushed to partner FTP: /out/transport/eventUpdate

Property Type Mandatory Description
messageHeader MessageHeader M Message Header information.
trackingId String M Shipment tracking ID (SPOT ID).
transportReferences Array[TransportReference] O Array of transport references.
references Array[TransportOrderReference] O Array of references. (Customer/Partner/…)
events Array[Event] M Array of events.

TransportReference

"transportReferences": [{
    "referenceType":"string",
    "value":"string"
}]
<transportReference>
    <referenceType>...</referenceType>
    <value>...</value>
</transportReference>
Property Type Mandatory Description
referenceType String M Type of transport reference MAWB, HAWB, MBL, HBL, JOBFILE_UKW_POSITION.
value String M Reference value.

Documents

Upload (Document only)

Example filename: 100149780_T103_testdocument.pdf

Using this method, only the document itself is needed but the filename must strictly follow the below described format, as the for the upload necessary metadata will be parsed from the filename.

Filename format: <spotTrackingId>_<documentType>_<filename>.<extensions>

FTP folder: /in/transport/documents

Property Type Mandatory Description
<spotTrackingId> String M SPOT shipment id. Used to assigne document to shipment.
<documentType> String M SPOT 4-letter document code. (Document type code list)
<filename> String M Filename which will be shown on uploaded document in SPOT.
<extension> String M Fileextension. E.g.: .pdf

Upload (Document + metadata)

Example document name: hardcopyPOD_12345.pdf
Example metadata name: hardcopyPOD_12345.xml

For the second method an additional metadata file is needed. This allows for the use of multiple and additional reference types. It is recommended to give the metadata file the same name as the document.

FTP folder: /in/transport/document

DocumentMetadata

{
    "filename" : "testdocument.pdf",
    "documentType" : "T103",
    "shipmentReferences":[{...}]
}
<?xml version="1.0" encoding="UTF-8" ?>
<documentMetadata>
    <filename>testdocument.pdf</filename>
    <documentType>T103</documentType>
    <shipmentReferences>...</shipmentReferences>
</documentMetadata>
Property Type Mandatory Description
filename String M Filename of document
documentType String M SPOT 4-letter document code. (Document type code list)
shipmentReferences Array[DocumentUploadReferences] M Array of references used to find shipment

DocumentUploadReferences

"shipmentReferences":[{
    "type":"TRACKING_ID",
    "value":"100149780"
}]
<shipmentReferences>
    <type>TRACKING_ID</type>
    <value>100149780</value>
</shipmentReferences>
Property Type Mandatory Description
type String M Type of reference. Valid values: TRACKING_ID, MAWB, HAWB, MBL, HBL, JOBFILE_UWK_POSITION
value String M Reference value.

Common Transport Objects

CargoDescription

"cargoDescription": [{
    "containerIndex":1,
    "cargoDetails": [{...}],
    "chargeableWeight": 0,
    "currencyCode": "string",
    "dangerousGoods": [{...}],
    "loadingMeters": 0,
    "valueOfGoods": 0
}]
<cargoDescription>
    <containerIndex>1</containerIndex>
    <cargoDetails>...</cargoDetails>
    <chargeableWeight>1.1</chargeableWeight>
    <currencyCode>string</currencyCode>
    <dangerousGoods>...</dangerousGoods>
    <loadingMeters>1.1</loadingMeters>
    <valueOfGoods>1.1</valueOfGoods>
</cargoDescription>
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

CargoDetails

"cargoDetails": [{
    "description": "string",
    "height": 0,
    "length": 0,
    "packageTypeCode": "string",
    "pieces": 0,
    "volume": 0,
    "weight": 0,
    "width": 0
 }]
<cargoDetails>
    <description>string</description>
    <height>1</height>
    <length>1</length>
    <packageTypeCode>string</packageTypeCode>
    <pieces>1</pieces>
    <volume>1.123</volume>
    <weight>1.1</weight>
    <width>1</width>
</cargoDetails>
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

"contacts": [{
  "emailBusiness": "string",
  "emailOther": "string",
  "externalReference": "string",
  "fax": {...},
  "firstName": "string",
  "jobRole": "string",
  "jobTitle": "string",
  "lastName": "string",
  "mobile": {...},
  "phoneBusiness": {...},
  "phoneOther": {...},
  "salutation": "MR",
  "title": "string"
}]
<contacts>
    <emailBusiness>string</emailBusiness>
    <emailOther>string</emailOther>
    <externalReference>string</externalReference>
    <fax>...</fax>
    <firstName>string</firstName>
    <jobRole>string</jobRole>
    <jobTitle>string</jobTitle>
    <lastName>string</lastName>
    <mobile>...</mobile>
    <phoneBusiness>...</phoneBusiness>
    <phoneOther>...</phoneOther>
    <salutation>MR</salutation>
    <title>string</title>
</contacts>
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

"containerDefinition": {
    "containers": [{...}],
    "currencyCode": "string",
    "generalCargoDescription": "string",
    "goodsValue": 0,
    "totalPieces": 0,
    "totalVolume": 0,
    "totalWeight": 0
}
<containerDefinition>
    <containers>...</containers>
    <currencyCode>string</currencyCode>
    <generalCargoDescription>string</generalCargoDescription>
    <goodsValue>1.1</goodsValue>
    <totalPieces>1</totalPieces>
    <totalVolume>1.1</totalVolume>
    <totalWeight>1.1</totalWeight>
</containerDefinition>
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

"containers": [{
    "containerIndex": 0,
    "containerNumber": "",
    "containerCode": "",
    "sealNumber": "",
    "atbNumber": "",
    "references":[{...}],
    "additionalAttributes":[...]
}]
<containers>
  <additionalAttributes>GOH</additionalAttributes>
  <atbNumber>string</atbNumber>
  <containerCode>string</containerCode>
  <containerIndex>1</containerIndex>
  <containerNumber>string</containerNumber>
  <references>...</references>
  <sealNumber>string</sealNumber>
</containers>
Property Type Mandatory Description
containerIndex Integer M Running number identifying a container.
containerNumber String O ISO 6346 container number.
containerCode String C ISO 6346 Standard Container Code. Mandatory for SEA FCL.
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

"events": [{
    "eventTypeIdentifier": "string",
    "eventTypeName": "string",
    "eventTimestamp": {...},
    "remark": "string",
    "containerNumber": "string",
    "eventLocation": {...},
    "additionalAttributes": [{...}]
}]
<events>
    <eventTypeIdentifier>7</eventTypeIdentifier>
    <eventTypeName>DEPARTED</eventTypeName>
    <eventTimestamp>...<eventTimestamp>
    <remark>Shipment departed from VIE</remark>
    <containerNumber/>
    <eventLocation>...</eventLocation>
    <additionalAttributes>...</additionalAttributes>
</events>
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.

EventLocation

"eventLocation": {
    "locationType": "string",
    "unlocodeLocation": {...},
    "iataLocation": {...},
    "addressLocation": {...},
    "freeLocation": {...}
}
<eventLocation>
    <locationType>string</locationType>
    <unlocodeLocation>...</unlocodeLocation>
    <iataLocation>...</iataLocation>
    <addressLocation>...</addressLocation>
    <freeLocation>...</freeLocation>
</eventLocation>

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.

EventUnlocodeLocation

"unlocodeLocation": {
    "unlocode":"string"
}
<unlocodeLocation>
    <unlocode>string</unlocode>
</unlocodeLocation>
Property Type Mandatory Description
unlocode String M UNLOCODE 5-letter location code.

EventIataLocation

"iataLocation": {
    "iataCode":"string"
}
<iataLocation>
    <iataCode>string</iataCode>
</iataLocation>
Property Type Mandatory Description
iataCode String M IATA 3-letter airport code.

EventAddressLocation

"addressLocation": {
    "city":"string",
    "street":"string",
    "postCode":"string",
    "countryCode":"string"
}
<addressLocation>
    <city>string</city>
    <street>string</street>
    <postcode>string</postcode>
    <countryCode>string</countryCode>
</addressLocation>
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

"freeLocation": {
    "name" : "string"
}
<freeLocation>
    <name>string</name>
</freeLocation>
Property Type Mandatory Description
name String M any free-text location information.

EventAdditionalAttribute

"additionalAttributes": [{
    "identifier":"string",
    "value":"string"
}]
<additionAttribute>
    <identifier>string</identifier>
    <value>string</value>
</additionAttribute>

Some events have additional attributes e.g.: DELIVERED has an attribute POD Name, which gives information about who accepted the delivery.

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

Insurance

"insurance": {
    "currencyCode": "string",
    "requiredBy": "CONSIGNEE",
    "value": 0
}
<insurance>
    <currencyCode>string</currencyCode>
    <requiredBy>CONSIGNEE</requiredBy>
    <value>1.1</value>
</insurance>
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

"oceanCarrier":{
    "name":"string",
    "scac":"string"
}
<oceanCarrier>
    <name>string</name>
    <scac>string</scac>
</oceanCarrier>
Property Type Mandatory Description
scac String M SCAC of carrier.
name String O Name of carrier.

Party

"shipper": {
  "accountNumber": "string",
  "city": "string",
  "contacts": [{...}],
  "countryCode": "string",
  "email": "string",
  "externalPartyIdentifier":"string",
  "externalReference": "string",
  "fax": {...},
  "matchCode": "string",
  "name": "string",
  "otherPhone": {...},
  "phone": {...},
  "state": "string",
  "street": "string",
  "zipCode": "string"
}
<shipper>
  <accountNumber>string</accountNumber>
  <city>string</city>
  <contacts>...</contacts>
  <countryCode>string</countryCode>
  <email>string</email>
  <externalPartyIdentifier>string</externalPartyIdentifier>
  <externalReference>string</externalReference>
  <fax>...</fax>
  <matchCode>string</matchCode>
  <name>string</name>
  <otherPhone>...</otherPhone>
  <phone>...</phone>
  <state>string</state>
  <street>string</street>
  <zipCode>string</zipCode>
</shipper>
Property Type Mandatory Description
accountNumber String O SPOT internal account number. If provided no additional info required.
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

"paymentDefinition": {
  "cashOnDelivery": 0,
  "codCurrencyCode": "string",
  "letterOfCredit": "string",
  "termsOfPayment": "CASH_AGAINST_DOCUMENT"
}
<paymentDefinition>
  <cashOnDelivery>1.1</cashOnDelivery>
  <codCurrencyCode>string</codCurrencyCode>
  <letterOfCredit>string</letterOfCredit>
  <termsOfPayment>CASH_AGAINST_DOCUMENT</termsOfPayment>
</paymentDefinition>
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 termsOfDelivery 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

"serviceSpecification": {
  "billOfLoadingType": "EMPTY",
  "serviceDefinition": "ECONOMY",
  "specialHandlingClassification": [
    "GARMET_ON_HANGER"
  ],
  "temperatureFrom": 0,
  "temperatureTo": 0
}
<serviceSpecification>
  <billOfLoadingType>EMPTY</billOfLoadingType>
  <serviceDefinition>ECONOMY</serviceDefinition>
  <specialHandlingClassification>GARMET_ON_HANGER</specialHandlingClassification>
  <temperatureFrom>1.1</temperatureFrom>
  <temperatureTo>1.1</temperatureTo>
</serviceSpecification>
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
temperatureFrom Decimal C Min. temperature. Mandatory if specialHandlingClassification contains TEMPERATURE_CONTROLLED
temperatureTo Decimal C Max. temperature. Mandatory if specialHandlingClassification contains TEMPERATURE_CONTROLLED

TransportOrderReference

"references": [{
    "referenceType":"string",
    "referenceKey":"string",
    "referenceNumber":"string"
}]
<references>
    <referenceType>string</referenceType>
    <referenceKey>string</extReferenceType>
    <referenceNumber>string</value>
</references>
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.

Logistics

Items

CREATE/GET Items

messageType: logistics.items

{
    "messageHeader":{...},
    "items":[{...}]
}
<?xml version="1.0" encoding="UTF-8" ?>
<ediMessage>
    <messageHeader>...</messageHeader>
    <items>...</items>
</ediMessage>

Sample files

Property Type Mandatory Description
messageHeader MessageHeader M Message header information
items Array[Item] M Item objects

Item

"items": [
    {
        "warehouse": {...},
        "itemCode": "ART-8456",
        "itemDescription1": "Article name",
        "itemDescription2": "Some more",
        "itemDescription3": "",
        "itemDescription4": "",
        "matchCode": "FIND-ME",
        "clearingUnit": "156446",
        "itemFamily": "Car",
        "itemGroup": "Body",
        "itemSubGroup": "Fenders",
        "originCountryCode": "AT",
        "itemConfiguration": {....},
        "packagingUnits": [{....}]
    }
]
<items>
    <item>
        <warehouse>...</warehouse>
        <itemCode>ART-8456</itemCode>
        <itemDescription1>Article name</itemDescription1>
        <itemDescription2>Some more</itemDescription2>
        <itemDescription3></itemDescription3>
        <itemDescription4></itemDescription4>
        <matchCode>FIND-ME</matchCode>
        <clearingUnit>156446</clearingUnit>
        <itemFamily>Car</itemFamily>
        <itemGroup>Body</itemGroup>
        <itemSubGroup>Fenders</itemSubGroup>
        <originCountryCode>AT</originCountryCode>
        <itemConfiguration>...</itemConfiguration>
        <packagingUnits>...</packagingUnits>
    </item>
</items>
Property Type Length Mandatory Description
warehouse Warehouse M Warehouse information.
itemCode String 20 M Item code of customer, used as reference for receipt/dispatch
itemDescription1 String 35 M Item description, name
itemDescription2 String 35 O Item description, additional text
itemDescription3 String 3 O Item description, additional text
itemDescription4 String 35 O Item description, additional text
matchCode String 35 O Matchcode, additional search attribute
clearingUnit String 15 O Customs clearing number or other reference to be printed on dispatch
itemFamily String 3 O Item family
itemGroup String 3 O Item group
itemSubGroup String 3 O Item sub-group
originCountryCode String 2 O Country code of item origin
itemConfiguration ItemConfiguration O Optional configuration for general item handling
packagingUnits Array[PackagingUnit] 1 - 6 M Packaging units of the item, level 1 is PCS

ItemConfiguration

"itemConfiguration": {
    "receiptDispatchEnabled": true,
    "eWarehouseEnabled": true,
    "allocationNumberEnabled": false,
    "batchNumberReceiptEnabled": false,
    "batchNumberDispatchEnabled": false,
    "serialNumberDispatchEnabled": false,
    "fifoLifo": "FIFO",
    "fifoDateType": "receipt",
    "minimalStock": 10,
    "maximalStock": 1000,
    "reorderStock": 50,
    "blockReason": ""
}
<itemConfiguration>
    <receiptDispatchEnabled>true</receiptDispatchEnabled>
    <eWarehouseEnabled>true</eWarehouseEnabled>
    <allocationNumberEnabled>false</allocationNumberEnabled>
    <batchNumberReceiptEnabled>false</batchNumberReceiptEnabled>
    <batchNumberDispatchEnabled>false</batchNumberDispatchEnabled>
    <serialNumberDispatchEnabled>false</serialNumberDispatchEnabled>
    <fifoLifo>FIFO</fifoLifo>
    <fifoDateType>receipt</fifoDateType>
    <minimalStock>10</minimalStock>
    <maximalStock>1000</maximalStock>
    <reorderStock>50</reorderStock>
    <blockReason></blockReason>
</itemConfiguration>
Property Type Length Mandatory Description
receiptDispatchEnabled Boolean O If enabled, receipt/dispatch of item is allowed
eWarehouseEnabled Boolean O If enabled, item will be shown in eWarehouse
allocationNumberEnabled Boolean O If enabled, the allocation numbers of items need to be recorded/considered on receipt/dispatch
batchNumberReceiptEnabled Boolean O If enabled, the batch numbers of items need to be recorded on receipt
batchNumberDispatchEnabled Boolean O If enabled, the batch numbers of items need to be recorded on dispatch. Is only effective, if “batchNumberReceiptEnabled” is also enabled.
serialNumberDispatchEnabled String O If enabled, the serial numbers of items need to be recorded on dispatch.
fifoLifo String 4 O FIFO or LIFO
fifoDateType String 15 O Distinction on which date the FIFO order depends (expiration/production/receipt)
minimalStock Integer O Minimal stock quantity
maximalStock Integer O Maximal stock quantity
reorderStock Integer O Reorder stock quantity
blockReason String 3 O Block Reason, default proposal for items receipt

Receipt Avisos

CREATE Receipt Avisos

messageType: logistics.receiptAviso

{
    "messageHeader":{...},
    "receiptAviso":{...}
}
<?xml version="1.0" encoding="UTF-8" ?>
<ediMessage>
    <messageHeader>...</messageHeader>
    <receiptAviso>...</aviso>
</ediMessage>

Create receipt avisos in logistics management system.

Sample files

Property Type Mandatory Description
messageHeader MessageHeader M Message header information
receiptAviso ReceiptAviso M Receipt aviso

RecieptAviso

"receiptAviso" : {
    "warehouse": {...}
    "customerReference1": "REF/8345",
    "customerReference2": "0015430"
    "supplierCode": "9997-SP",
    "supplierReference": "SUP44",
    "forwarderCode": "56435",
    "forwarderReference": "974-456",
    "comment": "attention please!",
    "goodsInDate": {...},
    "positions": [{...}],
}
<receiptAviso>
    <warehouse>...</warehouse>
    <customerReference1>REF/8345</customerReference1>
    <customerReference2>0015430</customerReference2>
    <supplierCode>9997-SP</supplierCode>
    <supplierReference>SUP44</supplierReference>
    <forwarderCode>56435</forwarderCode>
    <forwarderReference>974-456</forwarderReference>
    <comment>attention please!</comment>
    <goodsInDate>...</goodsInDate>
    <positions>...</positions>
</receiptAviso>
Property Type Length Mandatory Description
warehouse Warehouse M Warehouse information
customerReference1 String 35 M customer reference 1
customerReference2 String 35 O customer reference 2
supplierCode String 13 M* WMS supplier code, *) if not specified the warehouse/operative is taken
supplierReference String 35 O Reference of supplier
forwarderCode String 13 O WMS forwarder code
forwarderReference String 35 O Reference of forwarder
comment String 180 O Comments to the aviso
goodsInDate ApiDate M Planned entry date of goods into warehouse, time is not used
positions Array[ReceiptAvisoPosition] M Receipt aviso positions

ReceiptAvisoPosition

"positions": [
    {
        "clientPositionNumber": "010",
        "quantity": 8,
        "itemCode": "ART-8456",
        "itemCodeClient": "SUPART-1221",
        "batchNumber": "1654863",
        "allocationNumber": "44",
        "packagingType": "PAL",
        "mheReference": "SSCC-Number",
        "productionDate": {...},
        "bestBeforeDate": {...},
    }
]
<positions>
    <position>
        <clientPositionNumber>010</clientPositionNumber>
        <quantity>8</quantity>
        <itemCode>ART-8456</itemCode>
        <itemCodeClient>SUPART-1221</itemCodeClient>
        <batchNumber>1654863</batchNumber>
        <allocationNumber>44</allocationNumber>
        <packagingType>PAL</packagingType>
        <mheReference>SSCC-Number</mheReference>
        <productionDate>...</productionDate>
        <bestBeforeDate>...</bestBeforeDate>
    </position>
</positions>
Property Type Length Mandatory Description
clientPositionNumber String 5 O Position number from customer
quantity Integer 10 M Quantity in pieces (packing unit, smallest unit)
itemCode String 20 M Item number defined in item master database
itemCodeClient String 20 M Item number provided by client, e.g. supplier item code
batchNumber String 35 O Batch number
allocationNumber String 35 O Allocation number, if item is reserved for a project for example
packagingType String 3 O Packing unit e.g. PAL
mheReference String 35 O Reference MHE (= Mechanical Handling Equipment), e.g. SSCC-Number
productionDate ApiDate O Goods production date (if applicable to item), time is not used
bestBeforeDate ApiDate O Goods expiration date (if applicable to item), time is not used

Receipt Orders

CREATE Receipt Order

messageType: logistics.receiptOrder

{
    "messageHeader":{...},
    "receiptOrder":{...}
}
<?xml version="1.0" encoding="UTF-8" ?>
<ediMessage>
    <messageHeader>...</messageHeader>
    <receiptOrder>...</receiptOrder>
</ediMessage>

Create receipt orders in logistics management system.

Sample files

Property Type Mandatory Description
messageHeader MessageHeader M Message header information
receiptOrder ReceiptOrder M Receipt order

ReceiptOrder

"receiptOrder" : {
    "warehouse": {...}
    "customerReference1": "AB-123456",
    "customerReference1": "",
    "supplierCode": "SUP44",
    "supplierReference": "9997-SP",
    "forwarderCode": "56435",
    "forwarderReference": "974-456",
    "comment": "Glass - Fragile!",
    "receiverCode": "S-845",
    "positions": [{...}],
}
<receiptOrder>
    <warehouse>...</warehouse>
    <customerReference1>AB-123456</customerReference1>
    <customerReference2></customerReference2>
    <supplierCode>SUP44</supplierCode>
    <supplierReference>9997-SP</supplierReference>
    <forwarderCode>56435</forwarderCode>
    <forwarderReference>974-456</forwarderReference>
    <comment>Glass - Fragile!</comment>
    <receiverCode>S-845</receiverCode>
    <positions>...</positions>
</receiptOrder>
Property Type Length Mandatory Description
warehouse Warehouse M Warehouse information
customerReference1 String 35 M customer reference 1
customerReference2 String 35 O customer reference 2
supplierCode String 13 M* WMS supplier code, *) if not specified the warehouse/operative is taken
supplierReference String 35 O Reference of supplier
forwarderCode String 13 O WMS forwarder code
forwarderReference String 35 O Reference of forwarder
comment String 60 O Comments to the receipt order
receiverCode String 13 O WMS receiver code, if the goods receiver is already known
positions Array[ReceiptOrderPosition] M Receipt order positions

ReceiptOrderPosition

"positions": [
    {
        "clientPositionNumber": "010",
        "quantity": 8,
        "itemCode": "ART-8456",
        "batchNumber": "1654863",
        "allocationNumber": "44",
        "customsReference": "576438",
        "packagingType": "PAL",
        "mheReference": "SSCC-Number",
        "blockReason": "QLT",
        "productionDate": {...},
        "bestBeforeDate": {...},
    }
]
<positions>
    <position>
        <clientPositionNumber>010</clientPositionNumber>
        <itemCode>ART-8456</itemCode>
        <quantity>8</quantity>
        <batchNumber>1654863</batchNumber>
        <allocationNumber>44</allocationNumber>
        <customsReference>576438</customsReference>
        <packagingType>PAL</packagingType>
        <mheReference>SSCC-Number</mheReference>
        <blockReason>QLT</blockReason>
        <productionDate>...</productionDate>
        <bestBeforeDate>...</bestBeforeDate>
    </position>
</positions>
Property Type Length Mandatory Description
clientPositionNumber String 5 O Position number from customer
itemCode String 20 M Item number defined in item master database
quantity Integer 10 M Quantity in pieces (packing unit,smallest unit)
batchNumber String 35 O Batch number
allocationNumber String 35 O Allocation number, if item is reserved for a project for example
customsReference String 35 O Customs tariff code
packagingType String 3 O Packing unit e.g. PAL
mheReference String 35 O Reference MHE (=Mechanical Handling Equipment), e.g. SSCC-Number
blockReason String 3 O Reason for block QLT Quality check, GW Locked goods (damage)
productionDate ApiDate O Production date (if applicable to item), time is not used
bestBeforeDate ApiDate O Goods expiration date (if applicable to item), time is not used

Receipt Confirmations

GET Receipt Confirmations

messageType: logistics.receiptConfirmation

{
    "messageHeader":{...},
    "receiptOrderConfirmation":{...}
}
<?xml version="1.0" encoding="UTF-8" ?>
<ediMessage>
    <messageHeader>...</messageHeader>
    <receiptConfirmation>...</receiptConfirmation>
</ediMessage>

Sample files

Property Type Mandatory Description
messageHeader MessageHeader M Message header information
receiptConfirmation ReceiptConfirmation M Receipt confirmation

ReceiptConfirmation

"receiptConfirmation" : {
    "warehouse": {...}
    "receiptOrderId": 87954,
    "customerReference1": "AB-123456",
    "customerReference1": "",
    "supplier": {...},
    "supplierReference": "HSFR215",
    "forwarder": {...},
    "forwarderReference": "89796F",
    "goodsInDate": {...},
    "positions": [{...}],
}
<receiptConfirmation>
    <warehouse>...</warehouse>
    <receiptOrderId>87954</receiptOrderId>
    <customerReference1>AB-123456</customerReference1>
    <customerReference2></customerReference2>
    <supplier>...</supplier>
    <supplierReference>HSFR215</supplierReference>
    <forwarder>...</forwarder>
    <forwarderReference>89796F</forwarderReference>
    <goodsInDate>...</goodsInDate>
    <positions>...</positions>
</receiptConfirmation>
Property Type Length Mandatory Description
warehouse Warehouse M Warehouse information
receiptOrderId Integer 10 M ID generated for warehouse receipt order
customerReference1 String 35 M customer reference 1
customerReference2 String 35 O customer reference 2
supplier LogisticsParty O
supplierReference String 35 O Reference of supplier
forwarder LogisticsParty O
forwarderReference String 35 O Reference of forwarder
goodsInDate ApiDate O Entry date of goods into warehouse
positions Array[ReceiptConfirmationPosition] M Receipt confirmation positions

ReceiptConfirmationPosition

"positions": [
    {
        "positionNumber": 1,
        "clientPositionNumber": "010",
        "receiptAvisoPositionNumber": "2",
        "quantity": 5,
        "variableQuantity": 4,
        "itemCode": "ART-8456",
        "itemDescription1": "Article name",
        "itemDescription2": "Some more",
        "itemDescription3": "",
        "itemDescription4": "",
        "itemVolume": 2.47,
        "measureOfVolume": "m³",
        "itemWeight": 24.63
        "measureOfWeight": "kg",
        "eanCode": "5438245978836",
        "sscc": "SSCC-Number",
        "batchNumber": "1654863",
        "allocationNumber": "44",
        "customsReference": "8564168146",
        "packagingType": "PAL",
        "mheReference": "MHE-REF",
        "productionDate": {...},
        "bestBeforeDate": {...}
    }
]
<positions>
    <position>
        <positionNumber>1</positionNumber>
        <clientPositionNumber>010</clientPositionNumber>
        <receiptAvisoPositionNumber>2</receiptAvisoPositionNumber>
        <quantity>5</quantity>
        <variableQuantity>4</variableQuantity>
        <itemCode>ART-8456</itemCode>
        <itemDescription1>Article name</itemDescription1>
        <itemDescription2>Some more</itemDescription2>
        <itemDescription3></itemDescription3>
        <itemDescription4></itemDescription4>
        <itemVolume>2.47</itemVolume>
        <measureOfVolume></measureOfVolume>
        <itemWeight>24.63</itemWeight>
        <measureOfWeight>kg</measureOfWeight>
        <eanCode>5438245978836</eanCode>
        <sscc>SSCC-Number</sscc>
        <batchNumber>1654863</batchNumber>
        <allocationNumber>44</allocationNumber>
        <customsReference>8564168146</customsReference>
        <packagingType>PAL</packagingType>
        <mheReference>MHE-REF</mheReference>
        <productionDate>...</productionDate>
        <bestBeforeDate>...</bestBeforeDate>
    </position>
</positions>
Property Type Length Mandatory Description
positionNumber Integer 5 M Position number
clientPositionNumber String 5 O Position number from client
receiptAvisoPositionNumber String 10 M Position number from receipt aviso/order
quantity Integer 10 M Quantity in pieces (packing unit, smallest unit)
variableQuantity Integer 10,4 O Variable Quantity (running meter)
itemCode String 20 M Item number defined in item master database
itemDescription1 String 35 M Item description 1
itemDescription2 String 35 O Item description 2
itemDescription3 String 35 O Item description 3
itemDescription4 String 35 O Item description 4
itemVolume BigDecimal 10,6 O Item volume in m³
measureOfVolume String 3 C Mandatory, if itemVolume is filled. Currently always “m³”.
itemweight BigDecimal 10,4 O Item weight in kg
measureOfWeight String 3 C Mandatory, if itemWeight is filled. Currently always “kg”.
eanCode String 13 O European Article Number
sscc String 18 O SSCC-Number
batchNumber String 35 O Batch number
allocationNumber String 35 O Allocation number, if item is reserved for a project for example
customsReference String 35 O Customs reference
packagingType String 3 O Packaging type codes: PCS, BOX, PAL
mheReference String 35 O Reference MHE (= Mechanical Handling Equipment)
productionDate ApiDate O Goods production date, if applicable to item
bestBeforeDate ApiDate O Goods expiration date, if applicable to item

Dispatch Orders

CREATE Dispatch Orders

messageType: logistics.dispatchOrder

{
    "messageHeader":{...},
    "dispatchOrder":[{...}]
}
<?xml version="1.0" encoding="UTF-8" ?>
<ediMessage>
    <messageHeader>...</messageHeader>
    <dispatchOrder>...</dispatchOrder>
</ediMessage>

Creates a dispatch order in our warehouse system.

Sample files

Property Type Mandatory Description
messageHeader MessageHeader M Message header information
dispatchOrder DispatchOrder M Dispatch order

DispatchOrder

"dispatchOrder" : {
    "warehouse": {...},
    "customerReference1": "REF/8345",
    "customerReference2": "0015430"
    "orderReference": "ORD-987623",
    "receiver": {...},
    "deliveryDate": {...},
    "deliveryTerm": {...},
    "forwarderCode": "56435",
    "comment1": "Glass inside!",
    "comment2": "instructions can be here",
    "codValue": 92.70,
    "codCurrencyCode": "EUR",
    "positions": [{...}]
}
<dispatchOrder>
    <warehouse>...</warehouse>
    <customerReference1>"REF/8345</customerReference1>
    <customerReference2>0015430</customerReference2>
    <orderReference>ORD-987623</orderReference>
    <receiver>...</receiver>
    <deliveryDate>...</deliveryDate>
    <deliveryTerm>...</deliveryTerm>
    <forwarderCode>56435</forwarderCode>
    <comment1>Glass inside!</comment1>
    <comment2>instructions can be here</comment2>
    <codValue>92.70</codValue>
    <codCurrencyCode>EUR</codCurrencyCode>
    <positions>...</positions>
</dispatchOrder>
Property Type Length Mandatory Description
warehouse Warehouse M Information about warehouse
customerReference1 String 35 M Reference, all lines with the same reference are one dispatch order.
customerReference2 String 35 O Reference from customer.
orderReference String 35 O customer’s client order reference, if needed
receiver LogisticsParty M Receiver of dispatched goods
deliveryDate ApiDate 10 O Date of desired delivery, time is not used
deliveryTerm LogisticsDeliveryTerm O Delivery term and location
forwarderCode String 13 O Forwarder code defined in forwarder master database.
comment1 String 35 O short comment
comment2 String 160 O long comment
codValue BigDecimal 15,5 O Cash on delivery value
codCurrencyCode String 3 O Cash on delivery currency code
positions Array[DispatchOrderPosition] M Positions of dispatch orders

DispatchOrderPosition

"positions": [{
        "quantity": 5,
        "itemCode": "ART-8456",
        "batchNumber": "1654863",
        "allocationNumber": "44",
        "customsReference": "8564168146",
        "packagingType": "PAL",
        "pricePerItem": 18.54,
        "totalPrice": 92.70
        "currencyCode": "EUR",
    }
]
<positions>
    <position>
        <quantity>5</quantity>
        <itemCode>ART-8456</itemCode>
        <batchNumber>1654863</batchNumber>
        <allocationNumber>44</allocationNumber>
        <customsReference>8564168146</customsReference>
        <packagingType>PAL</packagingType>
        <pricePerItem>18.54</pricePerItem>
        <totalPrice>92.70</totalPrice>
        <currencyCode>EUR</currencyCode>
    </position>
</positions>
Property Type Length Mandatory Description
quantity Integer 10 M Quantity in pieces (packing unit level 1)
itemCode String 20 M Item number defined in item master database
batchNumber String 35 O Batch number
allocationNumber String 35 O Allocation number, if item is should be taken from an allocated (reserved) stock
customsReference String 35 O customs reference of item
packagingType String 3 O packagingType for item
pricePerItem BigDecimal 15,5 O Price per item
totalPrice BigDecimal 15,5 O Total price for items
currencyCode String 3 O ISO 4217 three letter currency code

Dispatch Confirmations

GET Dispatch Confirmations

messageType: logistics.dispatchConfirmation

{
    "messageHeader":{...},
    "dispatchConfirmation":{...}
}
<?xml version="1.0" encoding="UTF-8" ?>
<ediMessage>
    <messageHeader>...</messageHeader>
    <dispatchConfirmation>...</dispatchConfirmation>
</ediMessage>

Get dispatch confirmations from logistics management system.

Sample files

A customer receives a dispatch confirmation for delivery of goods from a warehouse to a receiver.

Property Type Mandatory Description
messageHeader MessageHeader M Message header information
dispatchConfirmation DispatchConfirmation M Dispatch confirmation

DispatchConfirmation

"dispatchConfirmation" : {
    "warehouse": {...},
    "dispatchOrderId": 34535,
    "customerReference1": "REF/8345",
    "customerReference2": "0015430"
    "orderReference": "ORD-987623",
    "orderDate": {...},
    "receiver": {...},
    "shippingMode": "ABH"
    "deliveryTerm": {...},
    "deliveryNoteNumber": "1538",
    "forwarder": {...},
    "positions": [{...}],
    "packages": [{...}],
}
<dispatchConfirmation>
    <warehouse>...</warehouse>
    <dispatchOrderId>34535</dispatchOrderId>
    <customerReference1></customerReference1>
    <customerReference2></customerReference2>
    <orderReference></orderReference>
    <orderDate>...</orderDate>
    <receiver>...</receiver>
    <shippingMode>ABH</shippingMode>
    <deliveryTerm>...</deliveryTerm>
    <deliveryNoteNumber>1538</deliveryNoteNumber>
    <forwarder>...</forwarder>
    <positions>...</positions>
    <packages>...</packages>
</dispatchConfirmation>
Property Type Length Mandatory Description
warehouse Warehouse M Information about warehouse
dispatchOrderId Integer O ID generated for warehouse dispatch order
customerReference1 String 35 M Reference from customer, taken from the corresponding dispatch order.
customerReference2 String 35 O Reference from customer, taken from the corresponding dispatch order.
orderReference String 35 O Order reference from customer’s client, taken from the corresponding dispatch order.
orderDate ApiDate O Dispatch order date
receiver LogisticsParty M Receiver of dispatch Confirmation
shippingMode String 3 O Valid values: ABH, SPE, PARABH=pick-up, SPE=freight forwarder, PAR=parcel service
deliveryTerm LogisticsDeliveryTerm M Delivery term and location
deliveryNoteNumber String 10 O Delivery note number
forwarder LogisticsParty M Forwarder of dispatch Confirmation
positions Array[DispatchConfirmationPosition] M Positions of dispatch orders
packages Array[DispatchConfirmationPackage] O Positions of dispatch orders

DispatchConfirmationPosition

"positions": [
    {
        "positionNumber": "1",
        "clientPositionNumber": "010",
        "quantity": 15,
        "variableQuantity": 4,
        "itemCode": "ART-8456",
        "itemdescription1": "Article name",
        "itemdescription2": "Some more",
        "itemdescription3": "",
        "itemdescription4": "",
        "itemVolume": 2.47,
        "measureOfVolume": "m³",
        "itemWeight": 24.63
        "measureOfWeight": "kg",
        "eanCode": "5438245978836",
        "sscc": "SSCC-Number",
        "batchNumber": "1654863",
        "allocationNumber": "44",
        "mhe": "MHE",
        "mheReference": "MHE-REF",
        "packagingType": "PAL",
        "customsReference": "8564168146",
        "clearingUnit": "CLU",
        "pricePerItem": 3,
        "totalPrice": 45,
        "currencyCode": "EUR",
        "productionDate": {...},
        "bestBeforeDate": {...}
    }
]
<positions>
    <position>
        <positionNumber>1</positionNumber>
        <clientPositionNumber>010</clientPositionNumber>
        <quantity>15</quantity>
        <variableQuantity>4</variableQuantity>
        <itemCode>ART-8456</itemCode>
        <itemDescription1>Artcle name</itemDescription1>
        <itemDescription2>Some more</itemDescription2>
        <itemDescription3></itemDescription3>
        <itemDescription4></itemDescription4>
        <itemVolume>2.47</itemVolume>
        <measureOfVolume></measureOfVolume>
        <itemWeight>24.63</itemWeight>
        <measureOfWeight>kg</measureOfWeight>
        <eanCode>5438245978836</eanCode>
        <sscc>SSCC-Number</sscc>
        <batchNumber>1654863</batchNumber>
        <allocationNumber>44</allocationNumber>
        <mhe>MHE</mhe>
        <mheReference>MHE-REF</mheReference>
        <packagingType>PAL</packagingType>
        <customsReference>8564168146</customsReference>
        <clearingUnit>CLU</clearingUnit>
        <pricePerItem>3</pricePerItem>
        <totalPrice>45</totalPrice>
        <currencyCode>EUR</currencyCode>
        <productionDate>...</productionDate>
        <bestBeforeDate>...</bestBeforeDate>
    </position>
</positions>
Property Type Length Mandatory Description
positionNumber String 5 M Position number
clientPositionNumber String 5 O Position number from client
quantity Integer M Quantity in pieces (packaging unit, smallest unit)
variableQuantity BigDecimal 10,4 O Variable Quantity (running meter)
itemCode String 20 M Item number defined in item master database
itemDescription1 String 35 M Item description 1
itemDescription2 String 35 O Item description 2
itemDescription3 String 35 O Item description 3
itemDescription4 String 35 O Item description 4
itemVolume BigDecimal 10,6 O Item volume
measureOfVolume String 3 C Mandatory, if itemVolume is filled. Currently always “m³”.
itemWeight BigDecimal 10,4 O Item weight
measureOfWeight String 3 C Mandatory, if itemWeight is filled. Currently always “kg”.
eanCode String 13 O European Article Number
sscc String 18 O SSCC Number
batchNumber String 35 O Batch number
allocationNumber String 35 O Allocation number, if item is reserved for a project for example
packagingType String 3 O Packaging type code of items
mhe String 3 O Packaging type code of Mechanical Handling package, if position items are packaged to another package
mheReference String 35 O Reference of MHE, e.g. SSCC-Number
customsReference String 35 O Customs reference
clearingUnit String 15 O
pricePerItem BigDecimal 15,5 O Price per item
totalPrice BigDecimal 15,5 O Total price of position
currencyCode String 3 C ISO 4217 three letter currency code. Mandatory, if pricePerItem or totalPrice are provided.
productionDate ApiDate O Goods production date, if applicable to item.
bestBeforeDate ApiDate O Goods expiration date, if applicable to item.

DispatchConfirmationPackage

"packages": [
    {
        "packageNumber": 1,
        "quantity": 2,
        "packagingType": "PAL",
        "length": 120,
        "width": 80,
        "height": 50,
        "measureOfDimension": "cm",
        "volume": 0.48,
        "measureOfVolume": "m³",
        "weight": 44.63,
        "measureOfWeight": "kg"
    }
]
<packages>
    <package>
        <packageNumber>1</packageNumber>
        <quantity>2</quantity>
        <packagingType>PAL</packagingType>
        <length>120</length>
        <width>80</width>
        <height>50</height>
        <measureOfDimension>cm</measureOfDimension>
        <volume>0.48</volume>
        <measureOfVolume></measureOfVolume>
        <weight>44.63</weight>
        <measureOfWeight>kg</measureOfWeight>
    </package>
</packages>
Property Type Length Mandatory Description
packageNumber Integer M continuous number of package
quantity Integer M Quantity of packages
packagingType String 3 M Packaging type code of package
length Integer O Length of package
width Integer O Width of package
height Integer O Height of package
measureOfDimension String 3 C Mandatory, if length/width/height are filled. Currently always “cm”.
volume BigDecimal 10,5 O Volume of package
measureOfVolume String 3 C Mandatory, if volume is filled. Currently always “m³”.
weight BigDecimal 10,2 O Weight of package
measureOfWeight String 3 C Mandatory, if itemWeight is filled. Currently always “kg”.

Inventory Reports

GET Inventory Reports

messageType: logistics.inventoryReport

Get inventory report for stock items.

Inventory Report

{
    "messageHeader":{...},
    "inventoryPositions":{...}
}
<?xml version="1.0" encoding="UTF-8" ?>
<ediMessage>
    <messageHeader>...</messageHeader>
    <inventoryPositions>...</inventoryPositions>
</ediMessage>

Sample files

Property Type Mandatory Description
messageHeader MessageHeader M Message header information
inventoryPositions Array[InventoryPosition] M Inventory

InventoryPosition

"inventoryPositions":{
    "warehouse": {...},
    "itemCode": "ART-8456",
    "description1": "Article name",
    "description2": "Some more",
    "description3": "",
    "description4": "",
    "itemGroup": "Car parts",
    "itemSubGroup": "Engine"
    "batchNumber": "1654863",
    "allocationNumber": "44",
    "variableQuantity": 0,
    "bestBeforeDate": {...},
    "packagingUnits": [{...}]
}
<inventoryPositions>
    <inventoryPosition>
        <warehouse>...</warehouse>
        <itemCode>ART-8456</itemCode>
        <description1>Article name</description1>
        <description2>Some more</description2>
        <description3></description3>
        <description4></description4>
        <itemGroup>Car parts</itemGroup>
        <itemSubGroup>Engine</itemSubGroup>
        <batchNumber>1654863</batchNumber>
        <allocationNumber>44</allocationNumber>
        <variableQuantity>1</variableQuantity>
        <bestBeforeDate>...</bestBeforeDate>
        <packagingUnits>...</packagingUnits>
    </inventoryPosition>
</inventoryPositions>
Property Type Length Mandatory Description
warehouse Warehouse M Information about warehouse
itemCode String 20 M Item code
description1 String 35 M Item description 1
description2 String 35 O Item description 2
description3 String 35 O Item description 3
description4 String 35 O Item description 4
itemGroup String 3 O Item group
itemSubGroup String 3 O Item subgroup
batchNumber String 35 O Batch number
allocationNumber String 35 O Allocation number
variableQuantity BigDecimal 10,4 O Variable quantity
bestBeforeDate ApiDate M Expiration date
packagingUnits Array[PackagingUnit] 1 - 6 M Packaging units of the item, level 1 is PCS

Common Logistics Objects

Warehouse

"warehouse":{
    "location":"CTO",
    "operative":"TEST"
}
<warehouse>
    <location>CTO</location>
    <operative>TEST</operative>
</warehouse>
Property Type Length Mandatory Description
location String 3 M Code were the Warehouse is located.
operative String 10 M Name of operative in warehouse system.

LogisticsParty

"logisticsParty": {
    "partyCode": "185961",
    "name1": "TEST Party",
    "name2": "",
    "name3": "",
    "address1": "Teststreet 20",
    "address2": "",
    "city": "VIENNA",
    "zipCode": "1010"
    "countryCode": "AT",
    "phone": {...},
    "fax": {...},
    "email": "test@example.com",
}
<logisticsParty>
    <partyCode>185961</partyCode>
    <name1>TEST Party</name1>
    <name2></name2>
    <name3></name3>
    <address1>Teststreet 20</address1>
    <address2></address2>
    <city>VIENNA</city>
    <zipCode>1010</zipCode>
    <countryCode>AT</countryCode>
    <phone>...</phone>
    <fax>...</fax>
    <email>test@example.com</email>
</logisticsParty>
Property Type Length Mandatory Description
partyCode String 13 C WMS party code. If provided no additional information is required.
name1 String 35 C Mandatory if no partyCode is provided.
name2 String 35 O
name3 String 35 O Only used for receiver/forwarder parties in dispatch confirmations
address1 String 35 C Mandatory if no partyCode is provided.
address2 String 35 O
city String 35 C Mandatory if no partyCode is provided.
zipCode String 13 O
countryCode String 3 C ISO country code (ISO 3166-1 Alpha-2). Mandatory if no partyCode is provided.
phone Phone 25 O
fax Phone 25 O
email String 50 O

PackagingUnit

"packagingUnits": [{
        "packagingType": "PCS",
        "packagingLevel": 1,
        "pieces": 1,
        "eanCode": "string13Chars",
        "weight": 9,
        "measureOfWeight": "kg",
        "length": 70,
        "width": 20,
        "height": 60,
        "measureOfDimension": "cm"
    }
]
<packagingUnits>
    <packagingUnit>
        <packagingType>PCS</packagingType>
        <packagingLevel>1</packagingLevel>
        <pieces>1</pieces>
        <eanCode>string13Chars</eanCode>
        <weight>9</weight>
        <measureOfWeight>kg</measureOfWeight>
        <length>70</length>
        <width>20</width>
        <height>60</height>
        <measureOfDimension>cm</measureOfDimension>
    </packagingUnit>
</packagingUnits>
Property Type Length Mandatory Description
packagingType String 3 M Packaging type codes: PCS, BOX, PAL
packagingLevel Integer M Packaging level 1-6 (smallest to largest unit, level 1 is PCS)
pieces Integer M Quantity of pieces of lowest packaging level within current level
eanCode String 13 O EAN-13 code
weight BigDecimal 10,4 O Total weight of packaging unit (will be converted/stored in kg)
measureOfWeight String 3 O Measure of weight. Default is kg, if not otherwise specified (t, kg, g, lbs)
length Integer O Length dimension (will be converted/stored in mm/cm)
width Integer O Width dimension (will be converted/stored in mm/cm)
height Integer O Height dimension (will be converted/stored in mm/cm)
measureOfDimension String 2 O Measure of dimensions. Default is cm, if not otherwise specified (m,cm, mm, ft, in)

LogisticsDeliveryTerm

"deliveryTerm": {
    "deliveryTermCode": "string",
    "deliveryTermLocation": "string",
}
<deliveryTerm>
    <deliveryTermCode>CFR</deliveryTermCode>
    <deliveryTermLocation>string</deliveryTermLocation>
</deliveryTerm>
Property Type Mandatory Description
deliveryTermCode String M 3-letter Incoterms® code. [(List of Incoterms®)][global-deliveryterms1].
deliveryTermLocation String M Location of delivery term.

Procurement

Purchase Orders

CREATE Purchase Orders

messageType: procurement.purchaseOrder

{
    "messageHeader":{...},
    "purchaseOrder":[{...}]
}
<?xml version="1.0" encoding="UTF-8" ?>
<purchaseOrder>
    <messageHeader>...</messageHeader>
    <purchaseOrder>...</purchaseOrder>
</purchaseOrder>

Create purchase orders in our purchase order management system.

Sample files

Property Type Mandatory Description
messageHeader MessageHeader M Message Header information.
purchaseOrders PurchaseOrder M Array of purchase orders.

PurchaseOrder

"purchaseOrders" : {
    "deliveryTerm": {...},
    "destinationCountryCode": "string",
    "lineItems": [{...}],
    "mainModality": "AIR",
    "orderDate": {...},
    "originCountryCode": "string",
    "parties": [{...}],
    "poReference": "string",
    "sourceIdentifier": "string"
}
<?xml version="1.0"?>

<PurchaseOrder>
    <deliveryTerm>...</deliveryTerm>
    <destinationCountryCode>string</destinationCountryCode>
    <lineItems>...</lineItems>
    <mainModality>AIR</mainModality>
    <orderDate>...</orderDate>
    <originCountryCode>string</originCountryCode>
    <parties>...</parties>
    <poReference>string</poReference>
    <sourceIdentifier>string</sourceIdentifier>
</PurchaseOrder>
Property Type Mandatory Description
deliveryTerm DeliveryTerm M 3-letter Incoterms® code.
destinationCountryCode String M ISO country code (ISO 3166-1 Alpha-2).
lineItems Array[PurchaseOrderLineItem] M
mainModality String M Main modality for Procurement. AIR, SEA, ROAD.
orderDate ApiDate M Order date from customer.
originCountryCode String M ISO country code (ISO 3166-1 Alpha-2).
parties Array[PurchaseOrderParty] M
poReference String M Customer’s purchase order number.
sourceIdentifier String M Will be provided from us. Identification for each customer.

Common Procurements Objects

PurchaseOrderLineItem

"lineItems": [{
        "article": {...},
        "cargoReady": {...},
        "cargoReadiness": {...},
        "desiredDelivery": {...},
        "estimatedArrival": {...},
        "estimatedDeparture": {...},
        "grossWeight": 0,
        "leadTime": 0,
        "mainModality": "AIR",
        "plannedQuantity": 0,
        "preCarriageTime": 0,
        "quantity": 0,
        "reference": "string",
        "volume": 0
    }
}
<lineItems>
    <article>...</article>
    <cargoReady>...</cargoReady>
    <cargoReadiness>...</cargoReadiness>
    <desiredDelivery>...</desiredDelivery>
    <estimatedArrival>...</estimatedArrival>
    <estimatedDeparture>...</estimatedDeparture>
    <grossWeight>1.1</grossWeight>
    <leadTime>1</leadTime>
    <mainModality>AIR</mainModality>
    <plannedQuantity>1</plannedQuantity>
    <preCarriageTime>1</preCarriageTime>
    <quantity>1</quantity>
    <reference>string</reference>
    <volume>1.1</volume>
</lineItems>
Property Type Mandatory Description
article PurchaseOrderArticle M
cargoReadiness ApiDate C Mandatory if status is planned for transport.
cargoReady ApiDateFromTo C Mandatory if DDto or leadtime is empty.
desiredDelivery ApiDateFromTo C Mandatory if Cargo ready to or leadtime is empty.
estimatedArrival ApiDate C Mandatory if status is planned for transport, planning pending.
estimatedDeparture ApiDate C Mandatory if status is planned for transport, planning pending.
grossWeight BigDecimal O Weight of article in KG with packaging.
leadTime Integer O Mandatory if not defined in system settings.
mainModality String M Main modality for procurement. AIR, SEA, ROAD.
plannedQuantity Integer O Mandatory if status planned for transport is set.
mainCarriage Integer C Mandatory if not defined in system settings.
preCarriageTime Integer C Mandatory if not defined in system settings.
quantity Integer M Quantity of lineitems.
reference String M ID for each lineitem.
volume BigDecimal O Volume of article in m³.

PurchaseOrderArticle

"article": {
    "code": "string",
    "customsTariffNumber": "string",
    "dangerousGoods": {...},
    "description": "string",
    "eanCode": "string",
    "netPrice": 12.4,
    "netWeight": 1.2,
    "originCountry": "AT"
    "supplierCode": "string"
    "supplierDescription": "string"
}
<article>
    <code>string</code>
    <customsTariffNumber>string</customsTariffNumber>
    <dangerousGoods>...</dangerousGoods>
    <description>string</description>
    <eanCode>string</eanCode>
    <netPrice>12.4</netPrice>
    <netWeight>1.2</netWeight>
    <originCountry>AT</originCountry>
    <supplierCode>string</supplierCode>
    <supplierDescription>string</supplierDescription>
</article>
Property Type Mandatory Description
code String M Article code.
customsTariffNumber String O HS-code, customs tariff number.
dangerousGoods DangerousGoods M
description String M Description of article.
eanCode String O European Article Number.
netPrice BigDecimal O Final price after deducting all discounts and rebates.
netWeight BigDecimal O Weight of article in KG without packaging.
originCountry String O ISO origin country code (ISO 3166-1 Alpha-2).
supplierCode String O Supplier’s article code.
supplierDescription String O Supplier’s article description.

PurchaseOrderParty

"parties": [{
        "contacts": [{...}],
        "partyId": 415645,
        "partyType": "PRINCIPAL"
    }
]
<parties>
    <contacts>...</contacts>
    <partyId>415645</partyId>
    <partyType>PRINCIPAL</partyType>
</parties>
Property Type Mandatory Description
contacts Array[PurchaseOrderContact] O Array for contact persons.
partyId Integer M Customer ID (Provided from us).
partyType String M Possible types below.
partyAddress PartyAddress O If no party ID is provided the address data have to be filled out.
PartyTypes
PRINCIPAL SHIPPER PICKUP CONSIGNEE DELIVERY CONTROLLING_AGENT ORIGIN_AGENT DESTINATION_AGENT TRANSIT_HUB THIRD_PARTY NOTIFY_AGENT CONTROLLING_OFFICE HANDLING_OFFICE CUSTOMER SUPPLIER

PurchaseOrderContact

"contacts": [{
        "contactPersonId": 0,
        "emailBusiness": "string",
        "firstName": "string",
        "lastName": "string",
        "mobile": "string",
        "phoneBusiness": "string"
    }
]
<contacts>
    <contactPersonId>1</contactPersonId>
    <emailBusiness>string</emailBusiness>
    <firstName>string</firstName>
    <lastName>string</lastName>
    <mobile>string</mobile>
    <phoneBusiness>string</phoneBusiness>
</contacts>
Property Type Mandatory Description
contactPersonId Integer C If an Id will be provided all other fields can be ignored.
emailBusiness String C Contact business email address.
firstName String C Mandatory if no ID is provided.
lastName String C Mandatory if no ID is provided.
mobile String C Mandatory if no ID is provided.
phoneBusiness String C Contact business phone number.

PurchaseOrderPartyAddress

"partyAddress": [{
        "externalReference": 0,
        "name": "string",
        "city": "string",
        "street": "string",
        "zipCode": "string",
        "countryCode": "string",
        "state": "string",
        "email": "string",
        "phone": {...},
        "fax": {...},
        "otherPhone": {...},
    }
]
<partyAddress>
    <externalReference>1</externalReference>
    <name>string</name>
    <city>string</city>
    <street>string</street>
    <zipCode>string</zipCode>
    <countryCode>string</countryCode>
    <state>string</state>
    <email>string</email>
    <phone>...</phone>
    <fax>...</fax>
    <otherPhone>...</otherPhone>
</partyAddress>

If no partyId or externalReference is provided address data is mandatory.

Property Type Mandatory Description
externalReference Integer C If an Id will be provided all other fields can be ignored.
name String C
city String C Name of the city/location.
street String C Street address part (including house, store, door numbers).
zipCode String C postal code of the city/location.
countryCode String C ISO country code (ISO 3166-1 Alpha-2).
state String O
email String C
phone Phone O
fax Phone O
otherPhone Phone O

Global Objects

ApiDate

"estimatedCargoReadiness":{
    "date":"date",
    "time":"time",
}
<estimatedCargoReadiness>
    <date>string</date>
    <time>string</time>
</estimatedCargoReadiness>
Property Type Length Mandatory Description
date String 10 M Date in format YYYY-MM-DD as defined by ISO 8601.
time String 8 O Local time of location in format hh:mm:ss as defined by ISO 8601.

ApiDateFromTo

"desiredPickup":{
    "dateFrom":"date",
    "timeFrom":"time",
    "dateTo":"date",
    "timeTo":"time",
}
<desiredPickup>
    <dateFrom>string</dateFrom>
    <dateTo>string</dateTo>
    <timeFrom>string</timeFrom>
    <timeTo>string</timeTo>
</desiredPickup>
Property Type Length Mandatory Description
dateFrom String 10 O Date in format YYYY-MM-DD as defined by ISO 8601.
dateTo String 10 O Date in format YYYY-MM-DD as defined by ISO 8601.
timeFrom String 8 O Local time of location in format hh:mm:ss as defined by ISO 8601.
timeTo String 8 O Local time of location in format hh:mm:ss as defined by ISO 8601.

DangerousGoods

"dangerousGoods": [{
    "classification": "string",
    "packagingGroup": "string",
    "unNumber": "string"
}]
<dangerousGoods>
    <classification>string</classification>
    <packagingGroup>string</packagingGroup>
    <unNumber>string</unNumber>
</dangerousGoods>
Property Type Mandatory Description
classification String M Dangerous goods classification
packagingGroup String C packaging group, if assigned to the IMO class
unNumber String M 4-digit number codes defined by the UN Committee of Experts on the Transport of Dangerous Goods

DeliveryTerm

"deliveryTerm": {
    "deliveryTerm": "string",
    "deliveryTermLocation": "string",
}
<deliveryTerm>
    <deliveryTerm>CFR</deliveryTerm>
    <deliveryTermLocation>string</deliveryTermLocation>
</deliveryTerm>
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 page of the International Chamber of Commerce and/or on the Wikipedia article regarding Incoterms® rules.

“Incoterms” is a trademark of the International Chamber of Commerce.

Phone

"phoneBusiness"{
    "countryCode": "string",
    "areaCode": "string",
    "localNumber": "string"
}
<phoneBusiness>
  <areaCode>string</areaCode>
  <countryCode>string</countryCode>
  <localNumber>string</localNumber>
</phoneBusiness>
Property Type Mandatory Description
countryCode String O ITU phone calling country code (e.g. 43 for Austria, 1 for USA, 852 for Hong Kong).
areaCode String O Area code within the country.
localNumber String M Local connection number (If number cannot be split put whole number here.)