Last updated

Appendix

Air Shipment Event Types

Below are the available Event Types for Air shipments and the descriptions for each Event Type.

Event TypeDescription
ARRIVAL_AT_STOPThe shipment has arrived at the stop. Stop can be airport, warehouse etc.
CONSIGNEE_NOTIFYThe Consignee has been notified of the arrival.
DELIVERYThe cargo has been delivered to the shipper.
DEPARTURE_FROM_STOPThe shipment has departed from the stop. Stop can be airport, warehouse etc.
EXCEPTION_LATE_DEPARTUREIf the actual time of departure is after the scheduled time of departure, then this event will be generated.
EXCEPTION_MISSED_CONNECTIONIf the estimated time of arrival is after the scheduled time of departure of the next flight, this event will be generated.
FLIGHT_BOOKINGFlight booking information.
LOAD_ONTO_VEHICLECargo has been loaded onto plane.
MANIFESTConfirmation of the number of items being shipped on a flight.
RECEIVE_FROM_SHIPPERThe cargo has been received from the shipper and is being prepared for the flight.
READY_FOR_CARRIAGEFreight approved as ready for carriage at the airport.
FREIGHT_ON_HANDThis code indicates that freight has been handed over to the ground handler at origin airport.
ISSUE_FREIGHT_BILLElectronic shipment information received correctly by airline.
PICKED_UPThe shipment has been picked up from the shipper.
RECEIVE_FROM_CARRIERThe cargo has been received from the carrier/flight.
HELDThis code indicates that shipment is being held by the airline for various reasons (including delays).
CUSTOMS_HOLDThe customs process has been held for the shipment.
OUT_FOR_DELIVERYThe shipment is out for delivery.
TRACKING_COMPLETEThe shipment has completed.
TRACKING_INITIATEThe time at which the shipment was created with AIR_WAYBILL in P44.
TRACKING_STARTThe time p44 started tracking the AIR_WAYBILL.
UNLOAD_FROM_VEHICLE
WARNINGThe shipment exists in the project44 system, but there is an issue that is preventing tracking. See WARNING Event Type below for more information on the meaning behind this event type and a sample JSON response. In the description field, potential messages include Carrier out of network, Duplicate subscription, Invalid identifier, or Tracking initialization failed.

All Event Types can sometimes return an ETA or ATA. Please connect with your project44 Customer Success Manager to identify which event types return an ETA or ATA most often for your shipments.

WARNING Event Type

The WARNING event type is returned when the shipment has been successfully created with project44 but there is an issue preventing tracking. An explanation of this issue is included in the description field for the event. Potential values for the description field include:

  • Carrier out of network
  • Duplicate subscription
  • Invalid identifier
  • Tracking initialization failed

Sample JSON response code with the WARNING event type:


{
   "shipment":{
      "id":"1a060d95-b135-4cb1-9146-2a805a2ebf50",
      "identifiers":[
         {
            "type":"CARRIER_SCAC",
            "value":"string"
         },
         {
            "type":"HOUSE_AIR_WAYBILL",
            "value":"string"
         }
      ],
      "shipmentShareLink":"string",
      "createdDateTime":"2023-01-17T17:05:46+0000"
   },
   "events":[
      {
         "dateTime":"2023-01-17T17:05:47+0000",
         "receivedDateTime":"2023-01-17T17:05:47+0000",
         "type":"WARNING",
         "description":"Carrier out of network"
      }
   ]
}

Air Shipment Expiry Event Types

The following table describes the Event Types that can be used to determine when an Air shipment has expired and is marked as COMPLETED in the system.

Event TypeDescription
TRACKING_END_BY_USERThe user has ended the tracking of the shipment.
TRACKING_END_DUE_TO_TIMEOUTThe tracking session has timed out. The shipment initialised with AIR_WAYBILL only is timed out after 30 days of shipment creation in the P44 system if no event leading to COMPLETED state is received. The shipment initialised with HOUSE_AIR_WAYBILL is timed out after 60 days of shipment creation in the P44 system if no event leading to COMPLETED state is received.
TRACKING_STOPTracking was ended via the API.

Air Shipment State Types

Below are the accepted State Type values for Air shipments and the Event Types that trigger a state type. The state of the shipment is determined by the most recent actual event type that has occurred.

State TypeStart Event
SCHEDULEDTRACKING_INITIATED, FLIGHT_BOOKING
IN_TRANSITPICKED_UP,DEPARTURE_FROM_STOP,LOAD_ONTO_VEHICLE, OUT_FOR_DELIVERY
AT_STOPRECEIVED_FROM_SHIPPER, ARRIVAL_AT_STOP,UNLOAD_FROM_VEHICLE,MANIFEST,CONSIGNEE_NOTIFY,FREIGHT_ON_HAND,CUSTOMS_CLEARANCE,RECEIVE_FROM_CARRIER,ISSUE_FREIGHT_BILL,READY_FOR_CARRIAGE
COMPLETEDDELIVERY , TRACKING_COMPLETE, TRACKING_END_BY_USER, TRACKING_END_DUE_TO_TIMEOUT, TRACKING_STOP
UNKNOWNN/A

Air Shipment Stop Types

Stop TypeDetails
ORIGINWhere the shipment is loaded onto the plane by the shipper to be transported.
DESTINATIONWhere the shipment is unloaded from the plane.
AIRPORTThe airport stop involved in air leg.
WAREHOUSEWarehouse involved in pre-carriage or on-carriage.
HUBHub involved in pre-carriage or on-carriage.
UNKNOWNAn undefined stop type.
TRANSFERWhere the transfer stop is.

Route Segment Identifiers

This table describes the route segment identifiers for Air shipments.

Route Segment IDDescription
AIR_WAYBILLProof of receipt of carried goods to the shipper. This is issued by the carrier.
FLIGHT_NUMBERThe flight number for the carried goods.
HOUSE_AIR_WAYBILLProof of receipt of carrier goods to the shipper. This is issued by the freight forwarder

Error Response Codes

This Appendix describes the schema and fields of the standard project44 API Error Response.

Below, find the API Error Response Schema:

400 Invalid Request

{
  "httpStatusCode": 400,
  "httpMessage": "string",
  "errorMessage": "string",
  "errors": [
    {
      "severity": "ERROR",
      "message": "string",
      "diagnostic": "string",
      "source": "SYSTEM"
    }
  ],
  "supportReferenceId": "string"
}

401 Invalid or missing credentials

{
  "httpStatusCode": 401,
  "httpMessage": "string",
  "errorMessage": "string",
  "errors": [
    {
      "severity": "ERROR",
      "message": "string",
      "diagnostic": "string",
      "source": "SYSTEM"
    }
  ],
  "supportReferenceId": "string"
}

403 User not authorized to perform this operation

{
  "httpStatusCode": 403,
  "httpMessage": "string",
  "errorMessage": "string",
  "errors": [
    {
      "severity": "ERROR",
      "message": "string",
      "diagnostic": "string",
      "source": "SYSTEM"
    }
  ],
  "supportReferenceId": "string"
}

404 Not found

{
  "httpStatusCode": 404,
  "httpMessage": "string",
  "errorMessage": "string",
  "errors": [
    {
      "severity": "ERROR",
      "message": "string",
      "diagnostic": "string",
      "source": "SYSTEM"
    }
  ],
  "supportReferenceId": "string"
}

The table below describes each field of the API Error Response:

Error Response FieldDescription
httpStatusCodeThe value of the HTTP status code. Possible values are: 400, 401, 403, or 404
httpMessageA brief description of the HTTP status code. Possible values are: Invalid request (httpStatusCode = 400), Invalid or missing credentials (httpStatusCode = 401), User not authorized to perform this operation (httpStatusCode = 403),or Shipment not found (httpStatusCode = 404)
errorMessageA detailed description of the error. For example: "errorMessage": "Text '2022-03-23T18:38:00Z' could not be parsed, unparsed text found at index 19"
errorsThis array contains more details about the error
errors.severityThe severity of this message. Possible values are: ERROR, WARNING, or INFO
error.messageMore information about the error. For example: Appointment in the Past
error.diagnosticDiagnostic information from project44 (The System) or from the Capacity Provider/Carrier. NOTE: In a Capacity Provider/Carrier integration, it would come only from project44.
error.sourceThe originator of the error message.  NOTE: In a Capacity Provider/Carrier integration, the originator will always be SYSTEM. Possible values are: SYSTEM (error from project44) or CAPACITY PROVIDER (error from the Capacity Provider or Carrier)
supportReferenceId A reference identifier used by project44 support to assist with certain error messages.