📦 Understanding SHIPMENT_CHANGE API Messages
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.
🧩 Components of an API Message
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
}
📂 Payload
The heart of the API message is the payload, which contains two primary attributes: Change and Shipment.
1. Change attribute: This section provides details about the change that triggered the API message. Key attributes include:
- Is final POD: Indicates whether the change is related to the final Proof of Delivery.
- Is POL (Port of Loading): Specifies whether this change pertains to the port of loading.
- Is transshipment location: Indicates if the change corresponds to a transshipment location.
- Move type: Describes whether the change is related to an arrival or departure.
- Containers: Lists the containers involved in the change.
- Carrier: Provides information about the carrier associated with the change.
- Reading: Indicates the timestamp for the arrival or departure, depending on the move type.
- Vessel: Specifies the vessel involved in the shipment.
- Location: Identifies the location associated with the change.
2. Shipment attribute: This section offers a comprehensive snapshot of the shipment at the time when the change occurred. It includes:
- Is solid: Indicates whether the shipment is solid.
- Containers: Lists the containers involved in the shipment.
- Transport plan legs: Provides details about the transport plan legs within the shipment.
- Sequence number: A reference to the order or sequence of the shipment.
🚀 Leveraging API Messages
API messages like this one enable you to track changes in your trade flows and shipments effectively. You can use them to:
- Monitor changes in shipment status.
- Gain deeper insights into specific events, such as arrivals and departures.
- Keep all stakeholders informed about critical updates.
- Automate processes based on real-time data.
In summary, API messages are powerful tools that allow you to stay on top of your trade flows and make informed decisions, ensuring the smooth flow of goods and information in your supply chain.