API messages play a crucial role in Dockflow, providing real-time updates and changes in your trade flows and shipments. In this guide, we'll delve into the details of an API message, using a real example, to help you understand its components and how to leverage it effectively.
Let's dissect a sample API message:
json
{
"hash":"bfd607f81bbdff8ae7761ca32e2b982fdc73fc0c",
"tradeflow_id":00001,
"type":"SHIPMENT_CHANGE",
"message_generated_event_date":"2023-09-25T18:10:20+00:00",
"type_x_tradeflow_id":"SHIPMENT_CHANGE_00001",
"type_x_tradeflow_id_x_transport_unit_id":"SHIPMENT_CHANGE_00001_",
"created_at":"2023-09-25T18:10:23+00:00",
"calculated_size_in_kb":18,
"payload":{
"type":"SHIPMENT_CHANGE",
"change":{
"is_final_pod":true,
"bill_of_lading_reference":"MEDUEB098200",
"is_pol":false,
"is_transshipment_location":false,
"containers":[
{
"reference":"MSDU7151560",
"container_type":"45G1",
"container_length":40,
"container_is_reefer":false}
],
"actual":false,
"carrier":{
"name":"MSC"
},
"reading":"2023-10-22T10:00:00+00:00",
"reading_event_date_extended":{
"event_date_local":"2023-10-22T12:00:00.000+02:00",
"event_date_zulu":"2023-10-22T10:00:00.000Z",
"timezone_abbreviation":"CEST",
"timezone_geo":"Europe/Brussels",
"timezone_utc_offset_minutes":120
},
"move_type":"arrival",
"predicted_at":"2023-09-25T18:10:20.000000Z",
"vessel":{
"name":"MSC ALANYA",
"imo_number":"9785483",
"mmsi_number":"636021123"
},
"location":{
"unlocode":"BEANR",
"name":"BE Antwerpen",
"timezone":"Europe/Brussels",
"coordinates":{
"lat":51.2663,
"lng":4.37077
},
"country":{
"name":"Belgium",
"iso_a2":"BE"
}
}
},
"shipment":{
"is_solid":true,
"containers":[
{
"reference":"MSDU7151560",
"container_type":"45G1",
"container_length":40,
"container_is_reefer":false}
],
"transport_plan_legs":[
{
"bill_of_lading_number":"MEDUEB098200",
"booking_number":null,
"carrier":{
"name":"MSC"
},
"sea_shipment_legs":[
{
"carrier":{
"name":"MSC"
},
"carrier_transport_unit":{
"name":"MSC HOUSTON",
"imo_number":"9463281",
"mmsi_number":"538008564"
},
"arrival":{
"type":"arrival",
"containers":[
{
"reference":"MSDU7151560",
"container_type":"45G1",
"container_length":40,
"container_is_reefer":false}
],
"location":{
"unlocode":"ZAZBA",
"name":"ZA Coega",
"timezone":"Africa/Johannesburg",
"coordinates":{
"lat":-33.46,
"lng":25.4
},
"country":{
"name":"South Africa",
"iso_a2":"ZA"
}
},
"carrier_transport_unit":{
"name":"MSC HOUSTON",
"imo_number":"9463281",
"mmsi_number":"538008564"
},
"carrier":{
"name":"MSC"
},
"actual":true,
"internal_voyage_sequence_reference":0,
"reading_log":[
{
"actual":true,
"event_date":"2023-09-24T03:30:29.000000Z",
"is_latest":true,
"is_latest_provisional":false,
"is_provisional":false,
"reading":"2023-09-13T10:00:00+00:00"
},
{
"actual":true,
"event_date":"2023-09-20T11:38:10.000000Z",
"is_latest":false,
"is_latest_provisional":true,
"is_provisional":false,
"reading":"2023-09-13T10:00:00+00:00"
}
],
"is_final_pod":false,
"is_pol":false,
"is_transshipment_location":true,
"transshipment_sequence_ref":1,
"is_postpod":false,
"is_prepol":false,
"latest_provisional_reading":"2023-09-13T10:00:00+00:00",
"first_known_reading":"2023-09-13T10:00:00.000Z",
"latest_confirmed_reading":"2023-09-13T10:00:00+00:00",
"first_confirmed_reading":"2023-09-13T10:00:00+00:00",
"latest_reading":"2023-09-13T10:00:00+00:00",
"latest_reading_extended":{
"event_date_local":"2023-09-13T12:00:00.000+02:00",
"event_date_zulu":"2023-09-13T10:00:00.000Z",
"timezone_abbreviation":"SAST",
"timezone_geo":"Africa/Johannesburg",
"timezone_utc_offset_minutes":120
}
},
"departure":{
"type":"departure",
"containers":[
{
"reference":"MSDU7151560",
"container_type":"45G1",
"container_length":40,
"container_is_reefer":false}
],
"location":{
"unlocode":"MZBEW",
"name":"MZ Beira",
"timezone":"Africa/Maputo",
"coordinates":{
"lat":-19.82676,
"lng":34.83322
},
"country":{
"name":"Mozambique",
"iso_a2":"MZ"
}
},
"carrier_transport_unit":{
"name":"MSC HOUSTON",
"imo_number":"9463281",
"mmsi_number":"538008564"
},
"carrier":{
"name":"MSC"
},
"actual":true,
"internal_voyage_sequence_reference":0,
"reading_log":[
{
"actual":true,
"event_date":"2023-09-24T03:30:16.000000Z",
"is_latest":true,
"is_latest_provisional":true,
"is_provisional":true,
"reading":"2023-08-29T10:00:00+00:00"
},
{
"actual":true,
"event_date":"2023-09-22T00:18:38.000000Z",
"is_latest":false,
"is_latest_provisional":false,
"is_provisional":true,
"reading":"2023-08-21T10:00:00+00:00"
},
{
"actual":true,
"event_date":"2023-09-20T11:38:05.000000Z",
"is_latest":false,
"is_latest_provisional":false,
"is_provisional":true,
"reading":"2023-08-29T10:00:00+00:00"
},
{
"actual":true,
"event_date":"2023-09-20T11:38:32.000000Z",
"is_latest":false,
"is_latest_provisional":false,
"is_provisional":true,
"reading":"2023-08-21T10:00:00+00:00"
}
],
"is_final_pod":false,
"is_pol":true,
"is_transshipment_location":false,
"transshipment_sequence_ref":null,
"is_postpod":false,
"is_prepol":false,
"latest_provisional_reading":"2023-08-29T10:00:00+00:00",
"first_known_reading":"2023-08-29T10:00:00.000Z",
"latest_confirmed_reading":"2023-08-29T10:00:00+00:00",
"first_confirmed_reading":"2023-08-29T10:00:00+00:00",
"latest_reading":"2023-08-29T10:00:00+00:00",
"latest_reading_extended":{
"event_date_local":"2023-08-29T12:00:00.000+02:00",
"event_date_zulu":"2023-08-29T10:00:00.000Z",
"timezone_abbreviation":"CAT",
"timezone_geo":"Africa/Maputo",
"timezone_utc_offset_minutes":120
}
}
}
]
}
],
"sequence_number":0
}
},
"api_message_version":2
}
The heart of the API message is the payload, which contains two primary attributes: Change and Shipment.