ICTSI
- Provider Information:
Id |
ictsi |
Type |
terminal |
Trace Type |
API |
Credentials |
Subscrition ID and Key for Envase |
Status |
draft |
Doc Status |
draft |
Doc Version |
1 |
- URLs:
Type |
URL |
Environment |
Request |
DEV |
- Terminals:
Terminal Name |
Location Code |
|---|---|
Marine International Container Terminal |
MICT |
Sub Bay International Terminal Corp. |
SBITC |
- Credentials:
Important
Credentials are Envase based.
{
"x-subscription-id": "enter subscription id",
"Ocp-Apim-Subscription-Key": "enter subscription key"
}
Request
Query Containers Request
Query containers using the following two requests including the credentials in headers of the request as following. Query containers using the following request by adding the API_KEY for the customer in the request url as following.
First request to get the container information.
POST https://dev-api.ictsi.net/external/tms/api/v2/getContainerDetails?container-type=import&facility-id=MICT&container-number={ContainerNumbers}
- Request Headers:
{
"x-subscription-id": "enter subscription id",
"Ocp-Apim-Subscription-Key": "enter subscription key",
"x-api-id": "container",
"x-request-product-id": "truck-management-system"
}
Note
Facility ID should match Terminal Location’s Identifier in above table.
Second request to get the container events to review the holds related event.
POST https://dev-api.ictsi.net/external/tms/api/v2/getContainerEvent?unique-key=={ContainerUniqueKey}
- Request Headers:
{
"x-subscription-id": "enter subscription id",
"Ocp-Apim-Subscription-Key": "enter subscription key",
"x-api-id": "container-event",
"x-request-product-id": "track-and-trace"
}
Responses
Query Containers Response
POST https://dev-api.ictsi.net/external/tms/api/v2/getContainerDetails?container-type=import&facility-id=MICT&container-number=0944249
Next response is for container number 0944249
{
"data": [
{
"unique_key": "ICTSI/PH/MICT/25878505",
"operator_id": "ICTSI",
"complex_id": "PH",
"facility_id": "MICT",
"visit_state": "3DEPARTED",
"container_nbr": "0944249",
"equipment_type": "4310",
"teu": 2.0,
"line_operator_id": "ONE",
"line_operator_name": "null",
"create_time": "null",
"category": "IMPRT",
"freight_kind": "FCL",
"goods_and_ctr_wt_kg": 10158.0,
"goods_ctr_wt_kg_advised": null,
"goods_ctr_wt_kg_gate_measured": null,
"goods_ctr_wt_kg_yard_measured": null,
"seal_nbr1": "Y",
"seal_nbr2": "null",
"seal_nbr3": "null",
"seal_nbr4": "null",
"stopped_vessel": "false",
"stopped_rail": "false",
"stopped_road": "false",
"imped_vessel": "null",
"imped_rail": "null",
"imped_road": "null",
"arrive_pos_loctype": "VESSEL",
"arrive_pos_locid": "SLUM046N",
"arrive_pos_slot": "341014",
"last_pos_loctype": "TRUCK",
"last_pos_locid": "TXB357",
"last_pos_slot": "null",
"time_in": "",
"time_out": "null",
"booking_number": "null",
"requires_power": "false",
"time_state_change": "null",
"pod": "null",
"transit_state": "S70_DEPARTED",
"nominal_length": "NOM40",
"reefer_type": "NON_RFR",
"iso_group": "VH",
"master_bl_nbr": "null",
"origin": "null",
"destination": "null",
"consignee_id": "null",
"consignee_name": "null",
"shipper_id": "null",
"shipper_name": "null",
"house_bl_nbr": "null",
"cargo_category": "null",
"cargo_consignee_id": "null",
"cargo_consignee_name": "null",
"cargo_shipper_id": "null",
"cargo_shipper_name": "null",
"cargo_origin": "null",
"shipper_declared_vgm": "10158",
"terminal_measured_vgm": "10158",
"last_free_day": "null",
"paid_thru_day": "null",
"power_last_free_day": "null",
"power_paid_thru_day": "null",
"ib_registry_nbr": "MSK-180-20",
"ob_registry_nbr": "null",
"entry_no": "null",
"requires_xray": "null",
"custom_tag": "null",
"ib_appointment_start_date": "null",
"ib_appointment_end_date": "null",
"ob_appointment_start_date": "null",
"ob_appointment_end_date": "null",
"shipper": "null",
"consignee": "null",
"show_tvarrival_status": "null",
"tv_arrival_status": "null",
"tv_arrival_remarks": [],
"ib_tv_arrival_status": "null",
"ob_tv_arrival_status": "null",
"ib_tv_arrival_remarks": [],
"ob_tv_arrival_remarks": [],
"house_bls": [],
"ib_id": "SLUM046N",
"ib_cv_mode": "VESSEL",
"ib_carrier_name": "SEASPAN LUMACO",
"ib_operator_name": "null",
"ib_inbound_vyg": "046N",
"ib_outbound_vyg": "046N",
"ob_id": "TXB357",
"ob_cv_mode": "TRUCK",
"ob_carrier_name": "null",
"ob_operator_name": "null",
"ob_inbound_vyg": "null",
"ob_outbound_vyg": "null",
"bizu_lineoper_gkey": "null",
"bizu_ibcarrier_gkey": "null",
"bizu_obcarrier_gkey": "null",
"bizu_shipper_gkey": "null",
"bizu_consignee_gkey": "null",
"cro_date": "null",
"gatepass_no": "1220054982",
"domestic": "null",
"remarks": "null",
"transit_state_descriptions": [
{
"language": "ar-iq",
"description": "الراحل"
},
{
"language": "en-us",
"description": "Departed"
},
{
"language": "hr-hr",
"description": "Otišao"
}
],
"customs_release": "null",
"actual_ib_visit_unique_key": "ICTSI/PH/MICT/10912107",
"actual_ob_visit_unique_key": "null",
"available_for_appt": "true",
"available_for_pickup": "null",
"mask_data": 1
}
],
"extra": {
"updatedTime": "2023-04-19T09:54:31Z"
}
}
Note
Facility ID should match Terminal Location’s Identifier in above table.
Not found Container Response
POST https://dev-api.ictsi.net/external/tms/api/v2/getContainerDetails?container-type=import&facility-id=MICT&container-number=1944249
If container number 1944249 is returned as not found then API returns the next response.
{
"data": [],
"extra": {
"updatedTime": "2023-04-19T09:57:09Z"
}
}
Query Container Events Response
POST https://dev-api.ictsi.net/external/tms/api/v2/getContainerEvent?unique-key=ICTSI/PH/MICT/31414696
Next response is for the container events ICTSI/PH/MICT/31414696.
{
"data": [
{
"unique_key": "ICTSI/PH/MICT/1046721815",
"operator_id": "ICTSI",
"complex_id": "PH",
"facility_id": "MICT",
"yard_id": "MICT",
"placed_by": "xps:ECN4",
"placed_time": "null",
"event_type": "UNIT_IN_VESSEL",
"event_descriptions": [
{
"language": "ar-iq",
"description": "دخلت الوحدة المرفق عبر السفينة"
},
{
"language": "en-us",
"description": "Unit entered facility via vessel"
},
{
"language": "hr-hr",
"description": "Jedinica je ušla u objekt preko plovila"
}
],
"notifiable": true,
"container_gkey": "ICTSI/PH/MICT/31414696",
"applied_to_id": "TICH0000001",
"notes": "null",
"field_changes": [],
"category": "Standard",
"sub_category": "null",
"sequence": 0
},
{
"unique_key": "ICTSI/PH/MICT/1046414783",
"operator_id": "ICTSI",
"complex_id": "PH",
"facility_id": "MICT",
"yard_id": "MICT",
"placed_by": "user:billinguser",
"placed_time": "null",
"event_type": "UNIT_HOLD_XRAY_SET",
"event_descriptions": [
{
"language": "en-us",
"description": "XRAY Hold set"
}
],
"notifiable": true,
"container_gkey": "ICTSI/PH/MICT/31414696",
"applied_to_id": "TICH0000001",
"notes": "null",
"field_changes": [],
"category": "Holds",
"sub_category": "customs_hold",
"sequence": 0
},
{
"unique_key": "ICTSI/PH/MICT/1045944177",
"operator_id": "ICTSI",
"complex_id": "PH",
"facility_id": "MICT",
"yard_id": "0",
"placed_by": "user:-edi-",
"placed_time": "null",
"event_type": "UNIT_CREATE",
"event_descriptions": [
{
"language": "ar-iq",
"description": "تم إنشاء الوحدة"
},
{
"language": "en-us",
"description": "Unit created"
},
{
"language": "hr-hr",
"description": "Jedinica stvorena"
}
],
"notifiable": true,
"container_gkey": "ICTSI/PH/MICT/31414696",
"applied_to_id": "TICH0000001",
"notes": "null",
"field_changes": [],
"category": "Standard",
"sub_category": "null",
"sequence": 0
},
{
"unique_key": "ICTSI/PH/MICT/1046726452",
"operator_id": "ICTSI",
"complex_id": "PH",
"facility_id": "MICT",
"yard_id": "MICT",
"placed_by": "xps:ECN4/RTG72/ep10278",
"placed_time": "null",
"event_type": "UNIT_DISCH",
"event_descriptions": [
{
"language": "ar-iq",
"description": "وحدة تفريغها من السفينة"
},
{
"language": "en-us",
"description": "Unit discharged from vessel"
},
{
"language": "hr-hr",
"description": "Jedinica ispuštena iz plovila"
}
],
"notifiable": true,
"container_gkey": "ICTSI/PH/MICT/31414696",
"applied_to_id": "TICH0000001",
"notes": "null",
"field_changes": [],
"category": "Standard",
"sub_category": "null",
"sequence": 0
},
{
"unique_key": "ICTSI/PH/MICT/1046415311",
"operator_id": "ICTSI",
"complex_id": "PH",
"facility_id": "MICT",
"yard_id": "MICT",
"placed_by": "user:billinguser",
"placed_time": "null",
"event_type": "UNIT_HOLD_XRAY_SET",
"event_descriptions": [
{
"language": "en-us",
"description": "XRAY Hold set"
}
],
"notifiable": true,
"container_gkey": "ICTSI/PH/MICT/31414696",
"applied_to_id": "TICH0000001",
"notes": "null",
"field_changes": [],
"category": "Holds",
"sub_category": "customs_hold",
"sequence": 0
}
],
"extra": {
"updatedTime": "2023-04-19T09:52:06Z"
}
}
Add container to watchlist Request
Adding container to watchlist using the following request including the credentials in headers of the request as following.
POST https://dev-api.ictsi.net/external/tms/api/v2/addToWatchList
- Request Headers:
{
"x-subscription-id": "enter subscription id",
"Ocp-Apim-Subscription-Key": "enter subscription key",
"x-api-id": "container",
"x-request-product-id": "truck-management-system",
"Content-Type": "application/json"
}
Note
Request body is different for Import, Export and Empty containers.
Import uses steamshipBL sent on <data.steamshipBL> when container is published.
Export uses bookingNumber sent on <data.bookingNumber> when container is published.
Empty does not require steamshipBL nor bookingNumber.
- Request Body for adding Import container to watchlist:
{
"watchLists": [
{
"type": "UNIT",
"facilityId": "enter facility-id",
"uniqueKey": "unique-key from getContainerDetails response",
"bolNumber": "steamshipBL sent on data when the container was published"
}
]
}
- Request Body for adding Export container to watchlist:
{
"watchLists": [
{
"type": "UNIT",
"facilityId": "enter facility-id",
"uniqueKey": "unique-key from getContainerDetails response",
"bookingNumber": "bookingNumber sent on data when the container was published"
}
]
}
- Request Body for adding Empty container to watchlist:
{
"watchLists": [
{
"type": "UNIT",
"facilityId": "enter facility-id",
"uniqueKey": "unique-key from getContainerDetails response"
}
]
}
Note
Important: when publishing a container if import container does not have steamshipBL or if it has invalid steamshipBL, then the container will not be added to watchlist. Same for export container, it will not be added to watchlist if it does not have bookingNumber or if it has invalid bookingNumber.
Which means a trace failure will be returned for this container with failure message explaning exactly the parameters sent on the request that caused the failure.
Trace failure example for message retured when not passing steamshipBL when publishing import container:
Trace failure due to missing validation data for steamshipBL, payload.data is missing <steamshipBL>
Trace failure example for message retured when passing invalid steamshipBL:
Trace failure when adding container to watchlist due to missing validation data for request body <{“watchLists”: [{“type”: “UNIT”, “uniqueKey”: “ICTSI/PH/MICT/1593214”, “facilityId”: “MICT”, “bolNumber”: “invalid steamshipBL”}]}>
Add container (import, export, empty) to watchlist Response.
{
"data": "OK, The watch list items were added successfully",
"extra": {
"updatedTime": "2023-07-05T11:05:00Z"
}
}
- Data Mapping:
Property |
Source Property |
Description |
|---|---|---|
id |
container_nbr |
The container reference number |
length |
nominal_length |
The container length. |
steamshipBL |
master_bl_nbr |
Bill of lading |
carrier.steamshipLine |
ib_operator_name |
Carrier scac. |
carrier.vessel |
ib_carrier_name |
Carrier vessel Name |
carrier.voyage |
ib_inbound_vyg |
Carrier voyage number |
isoCode |
equipment_type |
ISO Code |
destinationName |
facility_id |
Facility where this unit was handled |
eta |
eta |
Estimated Time Of Arrival |
customRelease |
customs_release |
Date for Custom Release |
- Arrived Event:
Property |
Source Property |
Description |
|---|---|---|
event[n].code
|
transit_state
|
Released event will be created
If transit state is S30_ECIN then it is arrived
|
event[n].date |
Default |
Today date is the default date value |
event[n].location.name |
arrive_pos_locid |
Arrived Location Id |
event[n].location.type |
arrive_pos_loctype |
Arrive Location Type (eg. VESSEL) |
event[n].location.siteId |
facility_id |
URN’s site identifying the location |
event[n].data.arrived |
Default |
ISO date of the arrival date |
- Ready For Appointment Event:
Property |
Source Property |
Description |
|---|---|---|
event[n].code
|
available_for_appt
|
if available_for_appt is true
we will create this event
|
event[n].date |
Default |
Today date is the default date value |
event[n].location.name |
Default |
Location value is defaulted to OFFDOCK |
event[n].location.type |
Default |
Terminal is the default type for location |
event[n].location.siteId |
facility_id |
URN’s site identifying the location |
event[n].data.readyForAppointment |
Default |
Displaying the status of an appointment |
- Lfd Event:
Property |
Source Property |
Description |
|---|---|---|
event[n].code
|
last_free_day
|
Lfd event will be created
If date in satisfiedthrough column
|
event[n].date |
Default |
Today date is the default date value |
event[n].location.name |
last_pos_slot |
Location could be YARD or VESSEL. |
event[n].location.type |
Default |
Terminal is the default type for location |
event[n].location.siteId |
Yardposition |
URN’s site identifying the location |
event[n].data.lfd
|
last_free_day
|
ISO date representing the last free
Date for the container
|
- Released Event:
Property |
Source Property |
Description |
|---|---|---|
event[n].code
|
transit_state
|
Released event will be created
If transit state is S50_ECOUT and S60_LOADED then it is released
|
event[n].date |
Default |
Today date is the default date value |
event[n].location.name |
Location |
Location could be YARD or VESSEL. |
event[n].location.type |
Default |
Terminal is the default type for location |
event[n].location.siteId |
Yardposition |
URN’s site identifying the location |
event[n].data.released |
Default |
ISO date of release date |
- Outgated Event:
Property |
Source Property |
Description |
|---|---|---|
event[n].code
|
transit_state
|
Released event will be created
If transit state is S70_DEPARTED then it is released
|
event[n].date |
Default |
Today date is the default date value |
event[n].location.name |
Default |
Location value is defaulted to OFFDOCK |
event[n].location.type |
Default |
Terminal is the default type for location |
event[n].data.outgate_confirmed
|
Default
|
Represents whether the
Event is confirmed or not
|
event[n].data.outgated |
time_out |
ISO date if the container was out gated |
- Hold Events:
Property |
Source Property |
Description |
|---|---|---|
event[n].code
|
imped_road
|
Indicate which hold event is created if condition is matched
Appointment Hold: if name is TABS_HOLD
Appointment Hold released: if name is TABS_HOLD_LIFT
Appointment Hold set: if name is TABS_HOLD_SET
|
event[n].date |
Default |
Today date is the default date value |
event[n].location.name |
Location |
Location could be YARD or VESSEL. |
event[n].location.type |
Default |
Terminal is the default type for location |