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 | https://apigateway.emodal.com/ | DEV/STG/PRD |
+-------------+---------------------------------------------+-------------+
| Retrieve | https://sb-emodalpro.servicebus.windows.net | 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:
.. code-block::
X-API-KEY ==> API_KEY
URL:
.. code-block::
POST https://apigateway.emodal.com/eds/ServiceOrder/ServiceOrders
Request Body:
.. code-block:: json
{
"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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block::
status code ==> 201
.. code-block:: json
[
{
"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."
}
]
}
]
Unauthorized publish response
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block::
status code ==> 401
.. code-block:: json
{
"type": "https://tools.ietf.org/html/rfc7235#section-3.1",
"title": "Unauthorized",
"status": 401,
"traceId": "00-f33d1fb1dcca9c4e9b2ef9b82de679ba-fc498a867b01cd4e-00"
}
Failed publish response
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block::
status code ==> 412
.. code-block:: json
[
{
"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:
.. code-block::
X-API-KEY ==> API_KEY
URL:
.. code-block::
POST https://apigateway.emodal.com/eds/ServiceOrder/ServiceOrdersStatus
Request Body:
.. code-block:: json
{
"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
.. code-block::
status code ==> 200
.. code-block:: json
{
"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.
.. code-block::
status code ==> 200
.. code-block:: json
{
"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
.. code-block::
status code ==> 200
.. code-block:: json
{
"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"
}
]
}
]
}
4 - Unauthorized check publish response
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block::
status code ==> 401
.. code-block:: json
{
"type": "https://tools.ietf.org/html/rfc7235#section-3.1",
"title": "Unauthorized",
"status": 401,
"traceId": "00-f33d1fb1dcca9c4e9b2ef9b82de679ba-fc498a867b01cd4e-00"
}
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:
.. code-block::
Authorization ==> SharedAccessSignature {SECRET_VALUE}
URL:
.. code-block::
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:
1 - Unauthorized
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This response happens when we don't provide the `SharedAccessSignature` in the `Authorization` header or
provide invalid one.
.. code-block::
status code ==> 401
2 - No content
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This response happens when there is no more updates in the queue.
.. code-block::
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.
.. code-block::
status code ==> 200
.. code-block:: json
{
"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
.. code-block :: json
{
"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 | |
+-------+-----------------------------------------------------------+