Migration guide for Generic Tracking v2
(Release Date: August 7, 2023)
If you are currently using our Generic Tracking v1 API then you will find valuable information
on how to migrate to Generic Tracking v2 in this document.
Summary:
--------
Key Features of Tracking v2:
1. Improved Event structure: Our updated event structure is more intuitive and user-friendly,
making it easier for you to monitor your shipments effortlessly. New event has been added.
2. Historical Event data removed: To gain a better data structure, all historical events has been removed.
Only the newest event will be shared.
3. New structure for Parties and date structure: The structure of the parties group is now in alignment with the structure
used in our Generic Booking v2.
Breaking Changes:
-----------------
- Changed the response format for "GET https://api.dsv.com/my/tracking/v2/shipments/reference/{reference}" to include additional data.
- Changed the response format for "GET https://api.dsv.com/my/tracking/v2/shipments/bookingId/{bookingId}" to include additional data.
- Changed the response format for "GET https://api.dsv.com/my/tracking/v2/shipments/tmsId/{tmsId}" to include additional data.
- Changed the response format for "GET https://api.dsv.com/my/tracking/v2/shipments/list" to include additional data.
Testing and Migration:
----------------------
To test Tracking version 2, use the above mention URLs or simply change the '/v1/' in your URL to '/v2/'.
You do not need a new subscription key to access the upgraded tracking version.
Structural Changes:
-------------------
"product":{ "name" Field name is unchanged but response value is updated to show correct case
"billOfLading" Moved from "transport/billOfLading" to "Product"
"containerMode" Moved from "transport/containerMode" to "product"
"awb" Moved from top level to "transport"
"grossWeightUom" Moved from top level to "goods"
"grossWeightValue" Moved from top level to "goods"
"loadingMetersUom" Moved from top level to "goods"
"loadingMetersValue" Moved from top level to "goods"
"quantityUom" Moved from top level to "goods"
"quantityValue" Moved from top level to "goods"
"volumeUom" Moved from top level to "goods"
"volumeValue" Moved from top level to "goods"
"parties": {} Changed to use same structure as Generic booking v2
https://developer.dsv.com/api-details#api=generic-booking-v2&operation=placeBooking&definition=Partiesfrom Version 1 (an array of objects)
"parties": [
{
"type": "SENDER",
"address": {
"name": "Test 123",
"alias": null,
"address1": "Test street 123",
"address2": null,
"address3": null,
"city": "Test 123",
"countryCode": "DK",
"state": null,
"zipCode": "1234",
"instructions": null,
"mdm": null
},
"contact": {
"name": "Reception",
"email": null,
"telephone": "+4512345678"
}
}
]
to Version 2 (an object of objects)
"parties": {
"sender": {
"address": {
"companyName": "Test 123", Field renamed from "name" to "companyName"
"addressId": null, Field renamed from "alias" to "addressId"
"addressLine1": "Test", Field renamed from "address1" to "addressLine1"
"addressLine2": null, Field renamed from "address2" to "addressLine2"
"addressLine3": null, Field renamed from "address3" to "addressLine3"
"city": "Test 123",
"countryCode": "DK",
"state": null,
"zipCode": "1234",
"instructions": null,
"mdm": null
},
"contact": {
"name": "Reception",
"email": null,
"telephone": "+4512345678"
}
}
}
"datetime": Changed to use same structure as Generic booking v2
https://developer.dsv.com/api-details#api=generic-booking-v2&operation=placeBooking&definition=DateTimeRange
from Version 1
"dateTime": {
"pickupDate": "2023-05-25",
"pickupTimeStart": "07:45:00",
"pickupTimeEnd": "09:45:00",
"deliveryDate": "2023-05-26",
"deliveryTimeStart": "14:30:00",
"deliveryTimeEnd": "16:30:00"
},
to Version 2
"dateTime": {
"pickupTime": {
"date": "2023-05-25", Field renamed from "pickupDate" to "date"
"start": "07:45:00", Field renamed from "pickupTimeStart" to "start"
"end": "09:45:00" Field renamed from "pickupTimeEnd" to "end"
},
"deliveryTime": {
"date": "2023-05-26", Field renamed from "deliveryDate" to "date"
"start": "14:30:00", Field renamed from "deliveryTimeStart" to "start"
"end": "16:30:00" Field renamed from "deliveryTimeEnd" to "end"
}
},
"events": Our updated event structure is more intuitive and user-friendly,
making it easier for you to monitor your shipments effortlessly. New event has been added.
Historical Event data is removed to gain a better data structure, all historical events has been removed.
Only the newest events will be shared.
from Version 1
"events": [
{
"date": "2023-05-16T14:57:00.000",
"location": {
"countryCode": "JP",
"code": "JPYOK",
"place": "Event"
},
"code": "Delivery",
"scopeType": "SHIPMENT",
"scopeValue": null,
"history": [
{
"date": "2023-05-17T14:57:00.000",
"location": {
"countryCode": "JP",
"code": "JPYOK",
"place": "Yokohama"
},
"code": "ESTIMATED_DELIVERY",
"scopeType": "SHIPMENT",
"scopeValue": null,
"history": []
}
]
}
],
to Version 2
"events": [
{
"eventGroup": "Delivery", Renamed from "events/code"
"eventDate": "2023-05-26T14:57:00.000", Renamed from "events/history/date"
"eventCode": "ESTIMATED_DELIVERY", Renamed from "events/history/code"
"eventDescription": "Estimated delivery", New field
"eventType": "SHIPMENT", Renamed from "events/history/scopeType"
"eventTypeValue": "SDSV1234567", Renamed from "events/history/scopeValue"
"location": { Moved from "events/history/location"
"countryCode": "JP", Moved from "events/history/location/countryCode"
"unlocode": "JPYOK", Renamed from "events/history/location/code"
"place": "Yokohama" Moved from "events/history/location/place"
},
"transportMode": null, New field
"vesselName": null, Renamed from "transport/mainVessel"
"voyageFlightNo": null, Renamed from "transport/mainVoyage & departingFlight & arrivingFlight"
"cargoCutOff": null, New field
"cargoAvailability": null, New field
"cancelled": false, New field
}
],
New fields:
-----------
"masterShipmentId" New Field on top level
"shipmentNotes" New Field on top level
"publicShipmentId" New field on top level
New arrays:
-----------
"childShipmentIds": [] New Array on top level
"issues": [ New array of objects
{
"issueDate": "",
"issuePointCode": "",
"issuePointDescription": "",
"issuePartyCode": "",
"issuePartyDescription": "",
"issueTypeCode": "",
"issueTypeDescription": "",
"issueReasonCode": "",
"issueReasonDescription": "",
"issueNotes": "",
"issueResolved": ""
}
],
"proofsOfDelivery": [ New array of objects
{
"documentId": "",
"documentType": "",
"typeDescription": "",
"createDate": "",
"fileName": "",
"fileType": "",
"downloadUrl": ""
}
],
"selectedServices": [ New array of objects
{
"name": "seaPortSelection",
"code": "SEA Ports selection",
"details": null
}
],
New objects:
------------
"customs": { New object
"shippedOnboardDate": "",
"customsStatus": "",
"entryNumber": "",
"forwarder": "",
"removalMode": ""
}
All other fields, object and arrays are unchanged from Version 1.
Contact and Support:
--------------------
For questions or assistance, contact our support team at developer.support@dsv.com or visit our developer portal.
