Gateway XML Tracking

The carrier gateway XML tracking format is designed by Viya to facilitate the communication of status changes (milestones) from the carrier towards the shipper. Milestones can be communicated on consignment or on handlingunit level. Changes to the format are made based on the feedback from carriers and shippers and the experience of Viya in the field.

Message format guidelines

• The format(s) should be implemented in a way that additional fields can be added without breaking the implementation.
  • Viya will only remove fields or change the meaning of a field in a new mayor version of the format.
• Date/Datetime fields are in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ where hh:mm:ss are 00:00:00 for date only
• XML is in UTF-8 format

Revision history

• 05-Sep-2024: Initial version
• 05-Sep-2024: Updated field descriptions

Supported message types

• Tracking: Message containing NEW status updates (milestones) for consignments or handling units.

Tracking

• The tracking message can be communicated through SFTP or HTTP.
  • HTTP endpoint is coming soon.
• The HTTP endpoint will return no body, only a status 200.
• Only NEW, previously untransmitted milestones should be contained in the tracking file. Do not repeat already communicated milestones in the file.
• The trackingReference.carrier field can be used to send a tracking reference on consignment or hanlingunit level.
• The shipper generally wants to be informed on the following events:
  • Departure of the goods (pickup)
  • Out for Delivery
  • Delivered
  • Exception (at least one event indicating a delay in delivery)
• A fixed list of document types is supported. Please contact Viya in case you require additional document types.

See examples and schema of the XML format.

Format

Root element <tracking>

Name	Type	Required	Description
carrier	Carrier	true	Information on the carrier sending the message
milestones	Milestones	true	Collection of milestones for one or more references

Carrier

tracking > carrier

Name	Type	Required	Description
name	string	true	Carrier name
reference	string	true	Unique reference to the carrier. To be agreed with Viya

Milestones

tracking > milestones

Name	Type	Required	Description
milestone	Milestone	true	Milestone for a specific reference

Milestone

tracking > milestones > milestone

Name	Type	Required	Description
trackingReference	Trackingreference	true	Collection of tracking references
trackingUrl	string	false	Full URL to the tracking event
equipment	Equipment	false	Information on the equipment used for the transport
events	Events	true	Collection of events for a specific reference

TrackingReference

tracking > milestones > milestone > trackingreference

Name	Type	Required	Description
shipper	string	false	Tracking reference code assigned by the shipper
carrier	string	true	Tracking reference code assigned by the carrier. This reference can be both consigment or hanlingunit level

Equipment

tracking > milestones > milestone > equipment

Name	Type	Required	Description
licencePlate	string	false	Licence plate of the equipment used for transport

Events

tracking > milestones > milestone > events

Name	Type	Required	Description
event	Event	true	New event

Event

tracking > milestones > milestone > events > event

Name	Type	Required	Description
eventDatetime	dateTime	true	Time at which this event occured. NOTE: Time zone specification is mandatory
eventDescription	string	false	General description on the event
scannedBy	string	false	Name of the entity that scanned the consignment when the event occured
eventMessage	string	false	Any descriptive text accompanying the event
eventType	EventType	true	The type of event as provided by the carrier
eventReason	EventReason	false	The reason why the event occured
eventLocation	EventLocation	false	Details on the location where the event took place
documents	Documents	false	Collection of documents related to the event

EventType

tracking > milestones > milestone > events > event > eventtype

Name	Type	Required	Description
code	string	true	The carrier provided type code for the event
description	string	false	The carrier provided description for the type of event

EventReason

tracking > milestones > milestone > events > event > eventreason

Name	Type	Required	Description
code	string	true	The carrier provided code for the reason the event took place
description	string	false	The carrier provided description for the reason the event took place

EventLocation

tracking > milestones > milestone > events > event > eventlocation

Name	Type	Required	Description
companyName	string	false	Name of the company where the event took place
address	Address	false	Address where the event took place
airportCode	string	false	Unique reference to an airport where the event took place
seaportCode	string	false	Unique reference to a seaport where the event took place
depotCode	string	false	Unique reference to a depot where the event took place

Documents

tracking > milestones > milestone > events > event > documents

Name	Type	Required	Description
Document	Document	false	Documents related to the event

EventLocationAddress

tracking > milestones > milestone > events > event > eventlocation > eventlocationaddress

Name	Type	Required	Description
addressLine1	string	false	Street name / PO Box and number
addressLine2	string	false	Apartment, suite, unit, building floor etc.
addressLine3	string	false	Additional address line for extra details
city	string	false	City of address
postCode	string	false	Postcode/zipcode
stateCode	string	false	State code used primarily for US, Canada, Italy
countryCode	CountryCode	false	2-digit ISO-3166 Country code

Document

tracking > milestones > milestone > events > event > documents > document

Name	Type	Required	Description
type	DocumentType	true	The type of document
content	string	true	Base64 encoded content of the file

Document Type

tracking > milestones > milestone > events > event > documents > document > documenttype

Name (enum)	description
ProofOfDeliverySignature	Proof of delivery signature
CMR	Signed Convention on the Contract for the International Carriage of Goods by Road
PictureOfDelivery	Picture of delivered goods
PictureOfDeliveryAttempt	Picture of the attempt to deliver the goods
PictureOfDamage	Picture of the damage on the goods
CashOnDeliveryReceipt	Receipt for cash on delivery proof
FreightInvoice	Invoice of the carrier to the shipper for the performed services regarding the shipment
Import	Documents related to the import of goods
Export	Documents related to the export of goods

CountryCode

Country codes based on ISO 3166, see wikipedia:

Codes

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW, AC, CP, CQ, DG, EA, EU, EZ, FX, IC, SU, TA, UK, UN, XK