Create a Shipment
Create a Rail shipment to initalize the shipment for tracking. There are different requirements for creating a rail shipment based on region (North America or Europe) and number of stops (this is specific to EU rail shipments only). These requirements are indicated in each use case below.
Create a North America Rail Shipment
Create a North America Rail shipment to be tracked in project44's network. This step is necessary before tracking of a Rail shipment can start.
Requirements
Have the following information, at a minimum, to successfully create a shipment:
- Shipment identifier (
CONTAINER_ID
,TRAILER_ID
, orRAIL_CAR_ID
)
Workflow
- Prepare a
POST
request to/api/v4/shipments/tracking
. For example:
{
"identifiers": [
{
"type": "TRAILER_ID",
"value": "string"
}
]
}
note
This only shows the minimum required request schema to create a North America rail shipment . To view the full request schema, see the API Reference documentation for this endpoint.
- Send the request.
Fields and Objects
Element | Description | Type | Notes |
---|---|---|---|
identifiers | A list of the shipment's identifying information. | array of identifiers | |
identifiers.type | The type of shipment identifier. | string | Valid values include: CONTAINER_ID , TRAILER_ID , or RAIL_CAR_ID . |
identifiers.value | The value of the shipment identifier. | string |
Expected System Response
You have successfully submitted the request when you receive a200 OK
response.{
"id": "string",
"identifiers": [
{
"type": "TRAILER_ID",
"value": "string"
}
]
}
note
This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the API Reference documentation for more information on required and potential null fields.
id
) is returned in the response after shipment creation. Store this ID to use in future API calls.Fields and Objects
Element | Description | Type | Notes |
---|---|---|---|
id | The shipment's master shipment ID. | string | The id will always be populated in the POST response. The id will always be populated in the POST response. Save this Shipment ID and use for future API calls. |
identifiers | A list of the shipment's identifying information. | Array of identifiers | |
identifiers.type | The type of shipment identifier. | string | Valid values for North American Rail identifiers include: CONTAINER_ID , TRAILER_ID , or RAIL_CAR_ID . |
identifiers.value | The value of the shipment identifier. | string |
Errors
If there was a problem with your request, you will receive one of the following error codes
400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation
See Error Response Codes in the Appendix for more information on the meaning of these error codes.
Create a Europe Rail Shipment with One Stop
Create a Europe Rail shipment with stop information that includes the running country or the start station. This step is necessary before tracking of a Rail shipment can start.
Requirements
Have the following information, at a minimum, to successfully create a shipment:
- Shipment identifier (
WAGON_ID
orTRAIN_NUMBER
) - Information for the
ORIGIN
stop, including the country code - Events with planned times
Workflow
- Prepare a
POST
request to/api/v4/shipments/tracking
. For example:
{
"identifiers": [
{
"type": "TRAIN_NUMBER",
"value": "string"
}
],
"routeInfo": {
"stops": [
{
"id": "string",
"type": "ORIGIN",
"location": {
"address": {
"country": "IT"
}
}
}
]
},
"events": [
{
"type": "DEPARTURE_FROM_STOP",
"stopId": "string",
"plannedDateTime": "2022-10-01T04:00:00+0000"
}
]
}
note
This only shows the minimum required request schema to create a Europe rail shipment with one stop. To view the full request schema, see the API Reference documentation for this endpoint.
- Send the request.
Fields and Objects
Element | Description | Type | Notes |
---|---|---|---|
identifiers | A list of the shipment's identifying information. | Array of identifiers | |
identifiers.type | The type of shipment identifier. | string | Valid values include: WAGON_ID or TRAIN_NUMBER . |
identifiers.value | The value of the shipment identifier. | string | |
routeInfo | An object of information for one stop. | object | |
routeInfo.stops | An array of the stop associated with the shipment. | Array of objects | |
routeInfo.stops.id | The uuid for the stop. | ||
routeInfo.stops.type | The type of stop. | string | Valid value is: ORIGIN . |
routeInfo.stops.location | The stop location object. | object | |
routeInfo.stops.location.address | The stop address object. | object | For shipments with one stop, the country code is mandatory. |
routeInfo.stops.location.address.country | The country code for the stop location. | string | See the API Reference Documentation for a list of valid values. |
events | Events for the shipment. | Array of objects | |
events.type | The type of event that will occur. | string | The event type depends on the stop type. Valid values include: |
events.stopId | The ID of the stop relevant to the event. | string | |
events.plannedDateTime | The planned time for when the event window will start. | string |
Expected System Response
You have successfully submitted the request when you receive a200 OK
response.{
"id": "string",
"identifiers": [
{
"type": "TRAIN_NUMBER",
"value": "string"
}
],
"routeInfo": {
"stops": [
{
"id": "string",
"type": "ORIGIN",
"location": {
"address": {
"country": "IT"
}
}
}
]
},
"events": [
{
"type": "DEPARTURE_FROM_STOP",
"stopId": "string",
"plannedDateTime": "2022-10-01T04:00:00+0000"
}
]
}
note
This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the API Reference documentation for more information on required and potential null fields.
id
) is returned in the response after shipment creation. Store this ID to use in future API calls.Fields and Objects
Element | Description | Type | Notes |
---|---|---|---|
id | The shipment's master shipment ID. | string | The id will always be populated in the POST response. Save this Shipment ID and use for future API calls. |
identifiers | A list of the shipment's identifying information. | Array of identifiers | |
identifiers.type | The type of shipment identifier. | string | Valid values for North American Rail identifiers include: WAGON_ID or TRAIN_NUMBER . |
identifiers.value | The value of the shipment identifier. | string | |
routeInfo | An object of information for one stop. | object | |
routeInfo.stops | An array of the stop associated with the shipment. | Array of objects | |
routeInfo.stops.id | The uuid for the stop. | ||
routeInfo.stops.type | The type of stop. | string | Valid value is: ORIGIN . |
routeInfo.stops.location | The stop location object. | object | |
routeInfo.stops.location.address | The stop address object. | object | For shipments with one stop, the country code is mandatory. |
routeInfo.stops.location.address.country | The country code for the stop location. | string | See the API Reference Documentation for a list of valid values. |
events | Events for the shipment. | Array of objects | |
events.type | The type of event that will occur. | string | The event type depends on the stop type. Valid values include: |
events.stopId | The ID of the stop relevant to the event. | string | |
events.plannedDateTime | The planned time for when the event window will start. | string |
Errors
If there was a problem with your request, you will receive one of the following error codes
400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation
See Error Response Codes in the Appendix for more information on the meaning of these error codes.
Create a Europe Rail Shipment with More than One Stop
Create a Europe Rail shipment with information for more than one stop. This step is necessary before tracking of a Rail shipment can start.
Requirements
Have the following information, at a minimum, to successfully create a shipment:
- Shipment identifier (
WAGON_ID
orTRAIN_NUMBER
) - Information for each stop, including either coordinates or the station identifiers, stop type, stop name, and stop ID
- Events with planned times
Workflow
- Prepare a
POST
request to/api/v4/shipments/tracking
. For example:
{
"identifiers": [
{
"type": "TRAIN_NUMBER",
"value": "string"
}
],
"routeInfo": {
"stops": [
{
"id": "string",
"type": "ORIGIN",
"location": {
"identifiers": [
{
"type": "RAIL_EU_PLC",
"value": "string"
}
],
"name": "string"
}
},
{
"id": "string",
"type": "DESTINATION",
"location": {
"identifiers": [
{
"type": "RAIL_EU_PLC",
"value": "string"
}
],
"name": "string"
}
}
]
},
"events": [
{
"type": "DEPARTURE_FROM_STOP",
"stopId": "string",
"plannedDateTime": "2022-10-01T04:00:00+0000"
},
{
"type": "ARRIVAL_AT_STOP",
"stopId": "string",
"plannedDateTime": "2022-10-01T22:00:00+0000"
}
]
}
note
This only shows the minimum required request schema to create a European rail shipment with more than one stop. To view the full request schema, see the API Reference documentation for this endpoint.
- Send the request.
Fields and Objects
Element | Description | Type | Notes |
---|---|---|---|
identifiers | A list of the shipment's identifying information. | Array of identifiers | |
identifiers.type | The type of shipment identifier. | string | Valid values include: WAGON_ID or TRAIN_NUMBER . |
identifiers.value | The value of the shipment identifier. | string | |
routeInfo | An object of information for one stop. | object | |
routeInfo.stops | An array of the stop associated with the shipment. | Array of objects | |
routeInfo.stops.id | The ID of the stop. | string | |
routeInfo.stops.type | The type of stop. | string | Valid values include: ORIGIN , DESTINATION , or TRANSFER . |
routeInfo.stops.location | The stop location object. | object | |
routeInfo.stops.location.identifiers | The list of standard identifiers for the location. | Array of objects | |
routeInfo.stops.location.identifiers.type | The type of location identifier. | string | Valid values include" RAIL_SPLC , RAIL_UIC , and RAIL_EU_PLC . |
routeInfo.stops.location.identifiers.value | The value of the location identifier. | string | |
routeInfo.stops.location.name | The stop address object. | object | For shipments with one stop, the country code is mandatory. |
events | Events for the shipment. | Array of objects | |
events.type | The type of event that will occur. | string | The event type depends on the stop type. Valid values include: Both |
events.stopId | The ID of the stop relevant to the event. | string | |
events.plannedDateTime | The planned time for when the event window will start. | string |
Expected System Response
You have successfully submitted the request when you receive a200 OK
response.{
"id": "string",
"identifiers": [
{
"type": "TRAIN_NUMBER",
"value": "string"
}
],
"shipmentShareLink": "string",
"createdDateTime": "2022-09-09T11:54:14+0000",
"routeInfo": {
"stops": [
{
"id": "string",
"type": "ORIGIN",
"location": {
"name": "string",
"identifiers": [
{
"type": "RAIL_EU_PLC",
"value": "string"
}
]
}
},
{
"id": "string",
"type": "DESTINATION",
"location": {
"name": "string",
"identifiers": [
{
"type": "RAIL_EU_PLC",
"value": "string"
}
]
}
}
]
},
"events": [
{
"type": "DEPARTURE_FROM_STOP",
"stopId": "string",
"plannedDateTime": "2022-10-01T04:00:00+0000"
},
{
"type": "ARRIVAL_AT_STOP",
"stopId": "string",
"plannedDateTime": "2022-10-01T22:00:00+0000"
}
]
}
note
This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the API Reference documentation for more information on required and potential null fields.
id
) is returned in the response after shipment creation. Store this ID to use in future API calls.Fields and Objects
Element | Description | Type | Notes |
---|---|---|---|
identifiers | A list of the shipment's identifying information. | Array of identifiers | |
identifiers.type | The type of shipment identifier. | string | Valid values include: WAGON_ID or TRAIN_NUMBER . |
identifiers.value | The value of the shipment identifier. | string | |
routeInfo | An object of information for one stop. | object | |
routeInfo.stops | An array of the stop associated with the shipment. | Array of objects | |
routeInfo.stops.id | The ID of the stop. | string | |
routeInfo.stops.type | The type of stop. | string | Valid values include: ORIGIN , DESTINATION , and TRANSFER . |
routeInfo.stops.location | The stop location object. | object | |
routeInfo.stops.location.identifiers | The list of standard identifiers for the location. | Array of objects | |
routeInfo.stops.location.identifiers.type | The type of location identifier. | string | Valid values include" RAIL_SPLC , RAIL_UIC , and RAIL_EU_PLC . |
routeInfo.stops.location.identifiers.value | The value of the location identifier. | string | |
routeInfo.stops.location.name | The stop address object. | object | For shipments with one stop, the country code is mandatory. |
events | Events for the shipment. | Array of objects | |
events.type | The type of event that will occur. | string | The event type depends on the stop type. Valid values include: Both |
events.stopId | The ID of the stop relevant to the event. | string | |
events.plannedDateTime | The planned time for when the event window will start. | string |
Errors
If there was a problem with your request, you will receive one of the following error codes
400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation
See Error Response Codes in the Appendix for more information on the meaning of these error codes.