If the body received by the create orchestration endpoint does not receive the expected format (JSON as described in the Create Orchestration section), an HTTP 400 error will be returned, and no orchestration will be created. Calling any of the status endpoints for the container will return HTTP 404 NOT FOUND.
If the body received by the create orchestration endpoint does not contain all required fields, or any of them does not match the expected format, such as a wrong or missing Port Code, an HTTP 412 error will be returned, and no orchestration will be created. Calling any of the status endpoints for the container will return HTTP 404 NOT FOUND.
On submitting an orchestration, if the port code is valid and the unit number matches the expected format, the orchestration creation request is accepted even if the unit is not yet reported to SprintPass Pro or the provided port does not match.
In this case, a notification will be sent informing that the unit was not found. The orchestration will be stopped automatically.
It may be possible that SprintPass Pro does not receive information about the unit until after it has been unloaded from the vessel for pick imports. The integrator logic should retry creating the orchestration on regular intervals until it is found. Orchestration created with warnings If all required parameters are correctly received the Create Orchestration endpoint returns HTTP 202 ACCEPTED. The orchestration is now operating. However, if any of the fields necessary to orchestrate Payments or Appointments are missing, the Orchestration Status endpoint shows all the warnings and errors generated by the orchestration system.
Note: calling the Orchestration Status endpoint always returns HTTP 200 for an existing orchestration -as this indicates a successful query to the system- but the true status of the orchestration should be extracted from the response JSON i. e. missing BOL will block the orchestration until it is indicated that the orchestration is allowed to proceed without a matching BOL by updating the orchestration.
After the orchestration request is successfully accepted, the orchestration can be stopped by any of the following events:
- Container not found
- Container gated in
- Orchestration canceled by integrator
If any of the above occur, the orchestration will be stopped automatically, and a notification will be sent to the integrator. See section “Receiving notifications”.
{
"orchestration_request": {
"trade_type": "I",
"unit_nbr": "ABCD1234567",
"notification_type": [],
},
"orchestration_status": {
"status": "STOPPED",
…
},
"unit_status": {
…
}
}If bill of lading is provided but does not match the one reported by eModal, the Orchestration adds a warning to the messages list:
{
"status": "ACTIVE",
"submitted_dttm": "2023-01-01T13:36:41.3270000",
"initiated_dttm": "2023-01-01T13:36:41.6470000"
"ended_dttm": null,
"messages": [
{
"message_cd": "10015",
"message_txt": "Non-matching Bill of Lading",
"message_severity_cd": "W"
},
{
"message_cd": "10007",
"message_txt": "Missing Guarantee Through Date",
"message_severity_cd": "W"
}
]
}Now, orchestration can be updated to indicate that payments are allowed to be resumed despite the BOL discrepancy:
PATCH /orchestrations/trade-type/{trade type}/unit-nbr/{unit_nbr}/locations/{location_type}
{
"guarantee_through_date": "2023-01-05"
} One warning will be removed and the orchestration will resume with paying fees. The BOL warning will remain but will not affect the orchestration in any way.
{
"status": "ACTIVE",
"submitted_dttm": "2023-01-01T13:36:41.3270000",
"initiated_dttm": "2023-01-01T13:36:41.6470000"
"ended_dttm": null,
"messages": [
{
"message_cd": "10015",
"message_txt": "Non-matching Bill of Lading",
"message_severity_cd": "W"
}
]
}If third party fees are supported i.e. PierPASS fees, but no other functionality is available for a terminal, the orchestration submits a claim for those fees and stops.
If third-party fees are supported and other functionality (appointments or terminal payments) is supported as well, the orchestration stays active:
{
"status": "ACTIVE",
"submitted_dttm": "2023-01-01T13:36:41.3270000",
"initiated_dttm": "2023-01-01T13:36:41.6470000"
"ended_dttm": null,
"messages": []
}The orchestration continues to perform other fee payments and appointment scheduling.
If visibility and payments are supported for a terminal, but there is not appointment scheduling available, the orchestration reports accordingly:
{
"status": "ACTIVE",
"submitted_dttm": "2023-01-01T13:36:41.3270000",
"initiated_dttm": "2023-01-01T13:36:41.6470000"
"ended_dttm": null,
"messages": [
{
"message_cd": "10024",
"message_txt": "Terminal not supported for appointments",
"message_severity_cd": "W"
}
]
}If an attempt to update appointment details if appointments are not supported:
{
"status": "ACTIVE",
"submitted_dttm": "2023-01-01T13:36:41.3270000",
"initiated_dttm": "2023-01-01T13:36:41.6470000"
"ended_dttm": null,
"messages": [
{
"message_cd": "10025",
"message_txt": "Terminal not supported for appointments",
"message_severity_cd": "C"
}
]
}Error code is different than 10023 as the severity is “critical”. The request is rejected.
If preferences match availability and no blockers are detected, an appointment is confirmed. Please note that even with a confirmed appointment, future cancelation events can occur.
{
"status": "ACTIVE",
"submitted_dttm": "2023-01-01T13:36:41.3270000",
"initiated_dttm": "2023-01-01T13:36:41.6470000"
"ended_dttm": null,
"messages": []
}GET /orchestrations/trade-type/{trade type}/unit-nbr/{unit_nbr}/unit-status 200 OK
{
"event_cat": "CTR",
"event_cd": "CNUPD",
"unitinfo": {
"unit_cat": "CONTAINER",
"unit_nbr": "ABCD1234567",
...
...
},
"unitstatusinfo": {
"status_cd": "Y"
"status_desc": "IN YARD",
"unituse_cd": "I",
"unituse_desc": "IMPORT"
},
"locations": [
{
"port_cd": "PORTA",
"port_nm": "Port of A",
"facility_cd": "FCLTA",
"facility_nm": "Facility A",
"locationtype_cd": "O",
"guarantee_through_date": "2023-01-05",
...
...
"locationinfo": {
...
...
},
"departureinfo": {
"carriertype_cd": "MC",
"carriertype_desc": "Motor Carrier",
"appointment_info": {
"reservation_status": "CONFIRMED",
"ticket_nbr": "FCLTA -0001-00001",
"pin_nbr": "1234",
"trucker_info": {
"trucker_scac": "ABCT",
"rfid_nbr": "",
"plate_nbr": "",
"company_nm": "ABCD TRANSPORT INC"
},
"driverinfo": {
"first_nm": "J",
"last_nm": "Doe"
},
"slot_info": {
"visit_dt": "2022-10-25",
"visitstart_tm": "07:00",
"visitend_tm": "07:30",
},
...
...
...
],
"holdinfo": [
{
"type": "OTHER",
"status": "RELEASED",
"status_dttm": "2023-01-01T17:17:34.294476",
"details": [
{
"hold_dttm": "2023-01-01T15:15:51.287916",
"holdreason_cd": "CF",
"holdreason_desc": "CTF Hold",
"release_dttm": "2023-01-01T17:17:34.294476",
"reportedby": "FCLTA"
}
]
},
{
"type": "OTHER",
"status": "RELEASED",
"status_dttm": "2023-01-01T17:17:34.294476",
"details": [
{
"hold_dttm": "2023-01-01T15:15:51.287916",
"holdreason_cd": "TM",
"holdreason_desc": "TMF Hold",
"release_dttm": "2023-01-01T17:17:34.294476",
"reportedby": "FCLTA"
}
]
}
]
"fee_receipts": [
{
"fee_cd": "PIERPASS",
"fee_desc": "TMF Fee",
"fee_amt": "68.42",
"fee_paid_dttm": "2023-01-01T00:00:00.0000000"
},
{
"fee_cd": "PIERPASS",
"fee_desc": "CTF Fee",
"fee_amt": "20.00",
"fee_paid_dttm": "2023-01-01T00:00:00.0000000"
}
],
...
...
...A slot may be confirmed by the terminal subject to conditions to be fulfilled prior to the execution. On example of this would be a hold. Some terminals may submit a confirmation with an active fee hold, expecting the company to clear it before executing the move.
Appointment is secured with pending actions
GET/orchestrations/trade-type/{trade type}/unit-nbr/{unit_nbr}/orchestration-status 200 OK
{
"status": "ACTIVE",
"submitted_dttm": "2023-01-01T13:36:41.3270000",
"initiated_dttm": "2023-01-01T13:36:41.6470000"
"ended_dttm": null,
"messages": []
}GET /orchestrations/trade-type/{trade type}/unit-nbr/{unit_nbr}/unit-status 200 OK
{
"event_cat": "CTR",
"event_cd": "CNUPD",
"unitinfo": {…},
"unitstatusinfo": {…},
"locations": [
{
...
...
"locationinfo": {
...
...
,
"departureinfo": {
…
"appointment_info": {
"reservation_status": "*CONFIRMED",
"ticket_nbr": " FCLTA -0001-00001",
"pin_nbr": "1234",
"trucker_info": {…},
"driverinfo": {…},
"slot_info": {…},
...
...
...
],
"holdinfo": [
{
"type": "OTHER",
"status": "HOLD",
"status_dttm": "2023-01-01T02:45:13.124999",
"details": [
{
"hold_dttm": "2022-12-30T09:45:06",
"holdreason_cd": "TM",
"holdreason_desc": "TMF Hold",
"release_dttm": null,
"reportedby": " FCLTA"
}
]
},
{
"type": "OTHER",
"status": "HOLD",
"status_dttm": "2023-01-01T02:45:13.124999",
"details": [
{
"hold_dttm": "2022-12-30T09:45:06",
"holdreason_cd": "CF",
"holdreason_desc": "CTF Hold",
"release_dttm": null,
"reportedby": " FCLTA"
}
]
}
],
"fee_receipts": [],
...
...
...If an appointment has been secured by the orchestration but it is later canceled by external action, such as terminal cancelation or trucker company cancelation via eModal web application, the appointment status will be reported accordingly:
GET/orchestrations/trade-type/{trade type}/unit-nbr/{unit_nbr}/orchestration-status 200 OK { "status": "ACTIVE", "submitted_dttm": "2023-01-01T13:36:41.3270000", "initiated_dttm": "2023-01-01T13:36:41.6470000" "ended_dttm": null, "messages": [] }
GET /orchestrations/trade-type/{trade type}/unit-nbr/{unit_nbr}/unit-status 200 OK { "event_cat": "CTR", "event_cd": "CNUPD", "unitinfo": { "unit_cat": "CONTAINER", "unit_nbr": "{unit_nbr}", ... ... },
"unitstatusinfo": { "status_cd": "Y" "status_desc": "IN YARD", "unituse_cd": "I",
"unituse_desc": "IMPORT" }, "locations": [ { "port_cd": "PORTA", "port_nm": "Port of A", "facility_cd": "FCLTA", "facility_nm": "Facility A", "locationtype_cd": "O", "guarantee_through_date": "2023-01-05", ... ... "locationinfo": { ... ... }, "departureinfo": { "carriertype_cd": "MC", "carriertype_desc": "Motor Carrier", "appointment_info": { "reservation_status": "CANCELED",
"ticket_nbr": "ABC-0001-00001",
"pin_nbr": "1234",
"trucker_info": {…}, "driverinfo": {…}, "slot_info": { "visit_dt": "2022-10-25", "visitstart_tm": "07:00", "visitend_tm": "07:30", }, ... ... ... ], "holdinfo": […], "fee_receipts": […] ... ... ...
Re-submit request to schedule an appointment on the first available slot
PATCH /orchestrations/trade-type/I/unit-nbr/ABCD1234567/locations/O
{ "reservation_details": {} }