eModal
- Provider Information:
Id |
emodal |
Type |
terminal |
Trace Type |
API |
Credentials |
API-KEY for publishing and SharedAccessSignature for retrieval and it is Envase based |
Limits |
Maximum number of containers per request is 1 |
Status |
in-progress |
Doc Status |
draft |
Doc Version |
1 |
- URLs:
Type |
URL |
Environment |
|---|---|---|
Publish |
DEV/STG/PRD |
|
Retrieve |
DEV/STG/PRD |
- Sites:
Name |
Site Id |
Description |
|---|---|---|
name |
ern |
the description |
Publish
Publish containers
Publishing containers requires an API_KEY that is being sent in X-API-KEY header
Headers:
X-API-KEY ==> API_KEY
URL:
POST https://apigateway.emodal.com/eds/ServiceOrder/ServiceOrders
Request Body:
{
"order": [{
"trade_type": "I",
"order_type": "",
"order_nbr": "",
"unit": {
"unit_nbr": "{CONTAINER_NUMBER i.e. CSQU305438}",
"unit_category": "CN"
},
"locations": [
{
"loc_type": "O",
"loc_port": "{LOC_PORT i.e. OAK}"
}
]
}]
}
Publish responses
Publish response can be one of the following:
Successful publish response
status code ==> 201
[
{
"service_order_nbr": "7e9ec40c-cf4e-42b2-99b5-c1fd1dd8da86",
"order_nbr": "",
"unit_nbr": "CSQU305438",
"tran_status": "S",
"msgs": [
{
"msg_sev": "I",
"msg_cd": "20045",
"msg_desc": "Service Order Created/Updated Successfully."
}
]
}
]
Failed publish response
status code ==> 412
[
{
"service_order_nbr": "00000000-0000-0000-0000-000000000000",
"order_nbr": "",
"unit_nbr": "CSQU305438",
"tran_status": "F",
"msgs": [
{
"msg_sev": "C",
"msg_cd": "{See below for error codes}",
"msg_desc": "{See below for error descriptions}"
}
]
}
]
Error codes and description:
Code |
Description |
|---|---|
20025 |
Cannot add service EMDES for container {CONTAINER_NUMBER}. The service has already been requested. |
20001 |
Container# {INVALID_CONTAINER_NUMBER} is invalid. |
30049 |
Invalid port code(loc_port) |
Check publish status
After publishing containers we need to check if the container found and can be traced or not. Checking publish containers status requires also an API_KEY that is being sent in X-API-KEY header
Headers:
X-API-KEY ==> API_KEY
URL:
POST https://apigateway.emodal.com/eds/ServiceOrder/ServiceOrdersStatus
Request Body:
{
"service_order_nbr": "{Service Order Number i.e. e967b778-e5eb-47a3-85f5-0ef30f2933cf}",
"sender_cd": "{SENDER_CD}"
}
Check publish status responses
Check publish status response can be one of the following:
1 - PENDING
This response means that the containers are still being requested
status code ==> 200
{
"service_order_nbr": "84fd8734-8a5c-4c3c-9818-3677a3bfc2bc",
"order_info": [
{
"status": "PENDING",
"unit_nbr": "BSIU9297052",
"status_info": null,
"services_status": [
{
"status": "PENDING",
"service_cd": "EMDES"
}
]
}
]
}
2 - REQUESTED
This response means that the containers has been requested successfully.
status code ==> 200
{
"service_order_nbr": "84fd8734-8a5c-4c3c-9818-3677a3bfc2bc",
"order_info": [
{
"status": "REQUESTED",
"unit_nbr": "BSIU9297052",
"status_info": null,
"services_status": [
{
"status": "REQUESTED",
"service_cd": "EMDES"
}
]
}
]
}
3 - ERROR
This response means that some error has occurred while requesting the containers. i.e. containers not found
status code ==> 200
{
"service_order_nbr": "8840f0fb-3760-4ea4-beba-eee9d236610f",
"order_info": [
{
"status": "ERROR",
"unit_nbr": "BSIU9297000",
"status_info": "Container not found, service order cannot be processed.",
"services_status": [
{
"status": "ERROR",
"service_cd": "EMDES"
}
]
}
]
}
Retrieve containers updates
After publishing containers, EDS (eModal Data service) starts to query containers and push the results updates into windows service bus queue. We can consume this queue by the following request using the SharedAccessSignature:
Headers:
Authorization ==> SharedAccessSignature {SECRET_VALUE}
URL:
DELETE https://sb-emodalpro.servicebus.windows.net/{TOPIC i.e. envase}/subscriptions/containerupdates/messages/head
Retrieve responses
Retrieve responses can be one of the following:
2 - No content
This response happens when there is no more updates in the queue.
status code ==> 204
3 - Container updates
This response happens when there is any updates for any published container in the queue and it is retrieved one by one.
status code ==> 200
{
"msgheader": {
"source_cd": "eModal",
"sender_cd": "EDS",
"company_cd": "{ENVASE_SENDER_CD}",
"receiver_cd": "{ENVASE_SENDER_CD}"
},
"msgdata": [
{
"instance_id": "166c5663-b38a-41a2-bd0d-cc203a499585",
"event_id": "83ee44c5-6fdf-4edc-ab1e-6460eb51543c",
"event_Nm": "Container Update",
"trans_dttm": "2021-10-26T21:43:00-07:00",
"unitinfo": {
"unit_cat": "CONTAINER",
"unit_nbr": "TRLU8685813",
"unittypeiso_cd": "4200",
"unitsztype_cd": "40DR",
"ownerline_scac": "ONEY",
"ownerline_cd": "ONE",
"tare_wgt": null,
"tarewgt_cd": null,
"tarewgt_unit": null,
"lastpretrip_dttm": null
},
"svceventinfo": null,
"unitstatusinfo": {
"status_cd": "Y",
"status_desc": "IN YARD",
"unituse_cd": "I",
"unituse_desc": "IMPORT"
},
"currentlocationinfo": {
"type": "Facility",
"facility_cd": "WUT",
"facility": "Washington United Terminals",
"lat": null,
"lon": null
},
"intransitinfo": null,
"arrivalinfo": {
"carriertype_cd": "VC",
"carriertype_desc": "VESSEL",
"carrier_cd": "9305673",
"rfid_nbr": null,
"plate_nbr": null,
"platestate_cd": null,
"driver_nm": null,
"svctype_cd": null,
"svctype_desc": null,
"ticket_nbr": null,
"appointment_info": null,
"appointmentstart_dttm": null,
"appointmentend_dttm": null,
"appointment_status": null,
"eta": null,
"ata": null
},
"departureinfo": null,
"routeinfo": {
"pol_cd": null,
"pod_cd": "NWSA",
"destination_cd": null,
"origin_cd": "WUT",
"vessel_cd": "9305673",
"vessel_nm": null,
"voyage_nbr": "133E",
"vslcdtype_cd": "Z",
"vslstowage_loc": null,
"vsl_eta": null,
"vsl_ata": null,
"vsl_etd": null,
"vsl_atd": null,
"cut_offs": null
},
"cargoinfo": {
"booking_nbr": null,
"bol_nbr": null,
"reefer_flg": "N",
"temp_min": null,
"mintemp_uom": null,
"temp_max": null,
"maxtemp_uom": null,
"hazmat_flg": "N",
"imoclass_cd": null,
"od_flg": "N",
"seal_nbr": null,
"bcocompany_nm": null,
"userline_scac": null
},
"feeinfo": null,
"shipmentstatusinfo": [
{
"shipmentstatus_cd": "CR",
"shipmentstatus_desc": "RELEASED",
"shipmentstatus_dttm": "10/08/2021 00:00:00"
},
{
"shipmentstatus_cd": "DN",
"shipmentstatus_desc": "CONTAINER NOT AVAILABLE FOR PICKUP",
"shipmentstatus_dttm": "2021-10-22"
},
{
"shipmentstatus_cd": "CT",
"shipmentstatus_desc": "CUSTOMS RELEASED",
"shipmentstatus_dttm": "2021-10-17"
},
{
"shipmentstatus_cd": "A",
"shipmentstatus_desc": "ARRIVED",
"shipmentstatus_dttm": "2021-10-17"
}
],
"currentconditioninfo": {
"damaged_flg": null,
"yard_loc": "81G",
"block_nbr": null,
"supply_temp": null,
"return_temp": null,
"set_temp": null,
"fullempty_cd": "FULL",
"gross_wgt": null,
"grosswgt_unit": null,
"actual_wgt": null,
"actualwgt_unit": null,
"genset_nbr": null,
"chassis_nbr": null,
"group_cd": null,
"tmf_flg": null
},
"gensetinfo": null,
"chassisinfo": null,
"lfdinfo": null,
"shipmentstatus": null,
"metadata": null
}
]
}
- Data Mapping:
Property |
Source Property |
Description |
|---|---|---|
container_number |
msgdata.unitinfo.unit_nbr |
The container number. |
carrier.steamshipLine |
msgdata.unitinfo.ownerline_scac |
Carrier steamship line. |
carrier.vessel |
msgdata.routeinfo.vessel_cd |
Carrier vessel number |
carrier.voyage |
msgdata.routeinfo.voyage_nbr |
Carrier voyage number |
steamshipBL |
msgdata.routeinfo.cargoinfo.bol_nbr |
Bill of lading |
pickup_number |
msgdata.routeinfo.cargoinfo.booking_nbr |
Pickup number |
destination.name |
msgdata.currentlocationinfo.facility |
The destination name if the container has arrived |
event.data.lot |
msgdata.currentconditioninfo.yard_loc |
The lot of the container in case it is grounded event |
event.data.eta |
msgdata.arrivalinfo.eta |
The ETA of the container that is used in ETA event |
Based on the shipment status info we can create the appropriate event
{
"shipmentstatusinfo": [
{
"shipmentstatus_cd": "{See below for STATUS_CODE}",
"shipmentstatus_desc": "{See below for DESC}",
"shipmentstatus_dttm": "10/25/2021 09:35:56"
}
]
}
Code |
Description |
|---|---|
A |
ARRIVED |
NF |
FREE TIME TO EXPIRE (used for determining last free day) |
CT |
Used for creating custom hold event |
PA |
|
PQ |
|
PR |
|
IB |
|
PS |
Used for creating USDA hold event |
PT |