Handling Booking Trace Results
Client applications will be notified of the trace results through the registered web-hooks with Envase Connect Data. The booking trace event will provide the information about the status of the booking, which has the following structure:
{
"orgId": "organizationId",
"svcId": "serviceId",
"type": "BOOKING",
"action": "TRACE_RESULTS",
"origin": "trace-booking-<environment>-notify-results",
"payload": {
"id": "2139165390",
"providerId": "lbct",
"locationCode": "LAX",
"steamshipLine": "OOLU",
"vessel": "EVER FRANK",
"vesselNumber": "9622588",
"voyage": "1054W",
"earliestLoading": "2023-03-21T07:00:00.000-07:00",
"arrived": "2023-02-28T04:48:00.000-08:00",
"etd": "2023-03-04T05:00:05.000-08:00",
"eta": "2023-03-03T05:00:05.000-08:00",
"departed": "2023-03-04T04:18:00.000-08:00",
"cutoff": "2023-03-28T16:00:00.000-07:00",
"reeferCutoff": "2023-03-30T02:00:00.000-07:00",
"oogCutoff": "2023-03-28T12:00:00.000-07:00",
"hazmatCutoff": "2023-03-27T16:00:00.000-07:00",
"hazmat": true,
"reefer": true,
"oogAllowed": false,
"totalContainers": 2,
"loadedContainers": 1,
"emptyContainers": 1,
"tracedAt": "2023-03-27T16:00:00.000-07:00",
"lastProviderUpdate": "2023-02-22T15:31:54.861-08:00",
"bookingDetails": [
{
"temperatureRequired": "-18",
"containerIso": "22G1",
"containerDescription": "20ft general",
"totalContainers": 2,
"loadedContainers": 1,
"hazmat": true,
"reefer": true,
"oogAllowed": false
}
]
}
}
The root properties orgId and svcId identify the client application and are used by Envase Connect Data to determine which web-hook will be notified. The type property will be set to BOOKING indicating that is a booking event, and the action will be set to TRACE_RESULT indicating that is a new result for the booking number being traced. As with other events, the origin property is provided by Envase Connect Data and client applications do not need to process that information.
The payload property contains a JSON object with the results of the trace with the following properties:
Name |
Type |
Description |
---|---|---|
id |
string |
The booking number being traced. |
providerId |
string |
Identifier of the provider providing the data. |
locationCode |
string |
Terminal/Rail specific identifier of the location. |
steamshipLine |
string |
Steamship line identifier/SCAC. |
vessel |
string |
Identifier of the vessel. |
vesselNumber |
string |
Reference number for the vessel. |
voyage |
string |
Reference number for the voyage. |
earliestLoading |
ISO Date/Time |
Date/Time when loading starts. |
arrived |
ISO Date/Time |
Date/Time the vessel arrived. |
etd |
ISO Date/Time |
Estimated time to departure. |
eta |
ISO Date/Time |
Estimated time to arrival. |
departed |
ISO Date/Time |
Date/Time the vessel departed. |
cutoff |
ISO Date/Time |
General cargo cutoff date/time. |
reeferCutoff |
ISO Date/Time |
Refrigerated cargo cutoff date/time. |
oogCutoff |
ISO Date/Time |
Out-of-gage cargo cutoff date/time. |
hazmatCutoff |
ISO Date/Time |
Hazmat cargo cutoff date/time. |
hazmat |
bool |
Allows hazardous materials, default is false. |
reefer |
bool |
Allows refrigerated cargo, default is false. |
oogAllowed |
bool |
Allows out of guage freight, default is false. |
totalContainers
|
number
|
Total number of containers in the booking reservation,
default is -1 which means its not provided.
|
loadedContainers
|
number
|
Number of containers that are loaded, default is -1
which means its not provided.
|
emptyContainers
|
number
|
Number of containers that are empty, default is -1
which means its not provided.
|
tracedAt |
ISO Date/Time |
Time where the booking was traced. |
lastProviderUpdate |
ISO Date/Time |
Date/Time the provider updated the data. |
bookingDetails[n].temperatureRequired |
sting |
Required temperature for a group of containers. |
bookingDetails[n].containerIso |
string |
Container iso id. |
bookingDetails[n].containerDescription |
string |
Container description. |
bookingDetails[n].totalContainers
|
number
|
Total number of containers, default is -1 which means
its not provided.
|
bookingDetails[n].loadedContainers
|
number
|
Number of loaded containers, default is -1 which
means its not provided.
|
bookingDetails[n].hazmat |
bool |
Containers has hazardous material, default is false. |
bookingDetails[n].reefer |
bool |
Containers are refrigerated, default is false. |
bookingDetails[n].oogAllowed |
bool |
Containers are out of guage, default is false. |
Handling Errors
Client applications will be notified when errors happen. Those errors fall into a couple of categories: trace errors and job failures. The structure of the events for those errors is similar, but client applications might want to handle them differently and take different actions.
Error indicating a job failure will have an action of JOB_FAILED. These errors represent a problem that will prevent all traces through a specific provider or for a specific customer.
As an example, imagine one of the provider APIs is down. Every booking traced through that API will fail because the site is down. A client application might want to notify the user that all their bookings through that site will not be traced because of problems with the provider.
Another example is an invalid credentials problem. Some sites require our customers to provide credentials to log into the provider site. When those credential expire, or are entered wrong, traces will fail until the problem is fixed. A client application will want to notify their users that the credential need to be reset or fixed.
The following is the structure of a JOB_FAILED event:
{
"orgId":"organizationId",
"svcId":"serviceId",
"type":"BOOKING",
"action":"JOB_FAILED",
"origin":"trace-booking-etbm-<environment>-send-job-error-event",
"payload":{
"siteId":"urn:site",
"providerId":"providerId",
"data":{
"message": "error message"
//Any additional info we need to add related to the error
// could be providerId, status_code or any other info
}
}
}
Errors that affect a specific booking are represented as trace errors events, and the action property will be set to TRACE_FAILED. These errors represents a problem with a specific booking at a specific trace time and client applications will want to handle them in different ways.
An example will be an error caused by an invalid or incorrect booking number. Client applications will want to notify the user that they should fix the problem and republish the booking for tracing.
The following shows the structure of a TRACE_FAILED event:
{
"orgId":"organizationId",
"svcId":"serviceId",
"type":"BOOKING",
"action":"TRACE_FAILED",
"origin":"trace-booking-etbm-<environment>-send-job-error-event",
"payload":{
"siteId":"urn:site",
"providerId":"providerId",
"id": "bookingId",
"data":{
"message": "error message"
//Any additional info we need to add related to the error
// could be providerId, status_code or any other info
}
}
}