Gateway Json Tracking

The carrier gateway JSON 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 or YYYY-MM-DDThh:mm:ss+01:00
• JSON is in UTF-8 format

Revision history

• 16-May-2025: Extracted from XML version

Endpoint

• The endpoint is a HTTP POST request to the following URL:
  • Production: https://{{customername}}.viya.me//api/carriers/carriergateway/tracking/events/v1
  • Test: https://{{customername}}.viya.me//api/carriers/carriergateway/tracking/events/v1?environment=test
  • The {{customername}} part of the URL is the name of the customer as agreed with Viya.
• Headers:
  • x-api-pat: is provided by Viya
  • Content-Type: application/json
• The HTTP endpoint will return:
  • status 202: If the message is accepted for processing
  • status 401: If the authentication failed
  • status 400: If the message is not well formed, with body containing description of the error
  • status 500: If the message is not accepted for processing

Guidelines

• Only NEW, previously untransmitted milestones should be contained in the tracking file. Do not repeat already communicated milestones in the file.
• Generally transmit 1 milestone as soon as the event occurs. It should be an exception to have multiple milestones for the same reference in one transmission.
• If transmission fails with a 500 error, the carrier should retry the transmission. The carrier should resolve content errors (400) before retrying.
• See examples of the JSON format.

Format

Root element

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,should match the carrierReference in the carrier profile that the shipper created in Viya

Milestones

tracking > 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
event	Event	true	The event for a specific reference

TrackingReference

tracking > milestone > trackingreference

At least one of handlingUnit or shipment is required. Both are allowed too.

This section is used to identify the shipment or handling unit for which the event is reported.

Name	Type	Required	Description
handlingUnit	trackingReferenceData	conditional	Tracking reference on handlingUnit level
shipment	trackingReferenceData	conditional	Tracking reference on shipment or consignment level

TrackingReferenceData

tracking > milestone > trackingreference > handlingUnit or shipment

Name	Type	Required	Description
shipperAssigned	string	false	Tracking reference code assigned by the shipper. This is the value provided in the reference field during booking.
carrierAssigned	string	true	Tracking reference code assigned by the carrier. This is the value provided in the trackingreference field during booking.

Equipment

tracking > milestone > equipment

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

Event

tracking > milestone > event

Name	Type	Required	Description
eventDateTime	dateTime	true	Time at which this event occurred. NOTE: Time zone specification is mandatory
estimatedDateTimeOfArrival	dateTime	false	Estimated Date that the item is expected to be delivered. NOTE: Time zone specification is not allowed
scannedBy	string	false	Name of the entity that scanned the consignment when the event occurred
message	string	false	Any descriptive text accompanying the event
type	EventType	true	The type of event as provided by the carrier
reason	EventReason	false	The reason why the event occurred
location	EventLocation	false	Details on the location where the event took place
documents	Documents	false	Collection of documents related to the event

EventType

tracking > milestone > event > type

Name	Type	Required	Description
code	string	true	The Viya type code for the event. See Tracking event codes for valid list of codes
description	string	false	The carrier provided description for the type of event

EventReason

tracking > milestone > event > reason

Name	Type	Required	Description
code	string	true	The Viya code for the reason the event took place. See Tracking event codes for valid list of reason codes for specific event.type.code
description	string	false	The carrier provided description for the reason the event took place

location

tracking > milestone > event > location

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 > milestone > event > documents

array of documents with properties:

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

Document Type

tracking > milestone > event > documents > 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

Address

tracking > milestone > event > location > address

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	true	2-digit ISO-3166 Country code
gpsCoordinates	GpsCoordinates	false	GPS coordinates of the location

GpsCoordinates

tracking > milestone > event > location > gpscoordinates

Name	Type	Required	Description
latitude	string	true	Latitude of the location
longitude	string	true	Longitude of the location

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