Appendix

Air Shipment Event Types

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

Event Type	Description
`ARRIVAL_AT_STOP`	The shipment has arrived at the stop. Stop can be airport, warehouse etc.
`CONSIGNEE_NOTIFY`	The Consignee has been notified of the arrival.
`DELIVERY`	The cargo has been delivered to the shipper.
`DEPARTURE_FROM_STOP`	The shipment has departed from the stop. Stop can be airport, warehouse etc.
`EXCEPTION_LATE_DEPARTURE`	If the actual time of departure is after the scheduled time of departure, then this event will be generated.
`EXCEPTION_MISSED_CONNECTION`	If the estimated time of arrival is after the scheduled time of departure of the next flight, this event will be generated.
`FLIGHT_BOOKING`	Flight booking information.
`LOAD_ONTO_VEHICLE`	Cargo has been loaded onto plane.
`MANIFEST`	Confirmation of the number of items being shipped on a flight.
`RECEIVE_FROM_SHIPPER`	The cargo has been received from the shipper and is being prepared for the flight.
`READY_FOR_CARRIAGE`	Freight approved as ready for carriage at the airport.
`FREIGHT_ON_HAND`	This code indicates that freight has been handed over to the ground handler at origin airport.
`ISSUE_FREIGHT_BILL`	Electronic shipment information received correctly by airline.
`PICKED_UP`	The shipment has been picked up from the shipper.
`RECEIVE_FROM_CARRIER`	The cargo has been received from the carrier/flight.
`HELD`	This code indicates that shipment is being held by the airline for various reasons (including delays).
`CUSTOMS_HOLD`	The customs process has been held for the shipment.
`OUT_FOR_DELIVERY`	The shipment is out for delivery.
`TRACKING_COMPLETE`	The shipment has completed.
`TRACKING_INITIATE`	The time at which the shipment was created with `AIR_WAYBILL` in P44.
`TRACKING_START`	The time p44 started tracking the `AIR_WAYBILL`.
`UNLOAD_FROM_VEHICLE`
`WARNING`	The 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 Type	Description
`TRACKING_END_BY_USER`	The user has ended the tracking of the shipment.
`TRACKING_END_DUE_TO_TIMEOUT`	The 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_STOP`	Tracking 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 Type	Start Event
`SCHEDULED`	`TRACKING_INITIATED`, `FLIGHT_BOOKING`
`IN_TRANSIT`	`PICKED_UP`,`DEPARTURE_FROM_STOP`,`LOAD_ONTO_VEHICLE`, `OUT_FOR_DELIVERY`
`AT_STOP`	`RECEIVED_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`
`COMPLETED`	`DELIVERY` , `TRACKING_COMPLETE`, `TRACKING_END_BY_USER`, `TRACKING_END_DUE_TO_TIMEOUT`, `TRACKING_STOP`
`UNKNOWN`	N/A

Air Shipment Stop Types

Stop Type	Details
`ORIGIN`	Where the shipment is loaded onto the plane by the shipper to be transported.
`DESTINATION`	Where the shipment is unloaded from the plane.
`AIRPORT`	The airport stop involved in air leg.
`WAREHOUSE`	Warehouse involved in pre-carriage or on-carriage.
`HUB`	Hub involved in pre-carriage or on-carriage.
`UNKNOWN`	An undefined stop type.
`TRANSFER`	Where the transfer stop is.

Route Segment Identifiers

This table describes the route segment identifiers for Air shipments.

Route Segment ID	Description
`AIR_WAYBILL`	Proof of receipt of carried goods to the shipper. This is issued by the carrier.
`FLIGHT_NUMBER`	The flight number for the carried goods.
`HOUSE_AIR_WAYBILL`	Proof 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 Field	Description
`httpStatusCode`	The value of the HTTP status code. Possible values are: `400`, `401`, `403`, or `404`
`httpMessage`	A 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)
`errorMessage`	A detailed description of the error. For example: `"errorMessage": "Text '2022-03-23T18:38:00Z' could not be parsed, unparsed text found at index 19"`
`errors`	This array contains more details about the error
`errors.severity`	The severity of this message. Possible values are: `ERROR`, `WARNING`, or `INFO`
`error.message`	More information about the error. For example: `Appointment in the Past`
`error.diagnostic`	Diagnostic 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.source`	The 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.