Receiving data from e4Cars
Receive vehicle status update information from e4Cars
As a customer, you have the ability to receive status updates for any of your vehicles.
Description
Subscribing to the logistics event "vehicle status progression for a customer" will trigger a call to an API in your domain.
How can I receive status updates for my vehicles?
Via API call: Status updates are sent to the REST API using the /POST or /PUT methods. You need to provide e4Cars with the API endpoint.
AUTHENTICATION: e4Cars supports two types of authentication methods:
- API KEY:
- Authentication in the header parameter using a static API key: you need to provide e4Cars with the parameter name and its value.
- Authentication using a static API key in QUERY Params: you need to provide e4Cars with the parameter name and its value.
- Basic authentication: you need to provide e4Cars with the username and password:
Authorization: Basic <Base64(username:password)>
METHOD: e4Cars supports the following HTTP methods for order push:
- /POST
- /PUT
PARAMS: e4Cars will be able to handle the following parameters during the call if needed:
- PATH Params
- QUERY Params
REQUEST parameters
- body (JSON Object, required): By default, it contains the standard E4Cars JSON object: OutgoingEvent.
OutgoingEvent schema
export interface OutgoingEvent {
"vin": string,
"license_plate": string,
"event": {
"family": string,
"type": string,
"creation_datetime_utc": string,
"real_date": : {
"date": string,
"utc_date": string
},
"location": {
"name": string,
"display_place_name": string,
"place_name": string,
"zip": string,
"city": string,
"country_code": string,
"platform": {
"code": string,
"name": string
}
}
},
"vehicle_account": {
"vehicle_account_no": string,
"customer_references" : CustomerReference[],
"logistics_status": string
},
"order": {
"read_url": string,
},
}
export interface CustomerReference {
"key": string;
"value": string;
}
OutgoingEvent Body Example
{
"vin": "STA207LBX1REB9164",
"license_plate": null,
"event": {
"family": "order_execution",
"type": "trip_delivery_ended",
"creation_datetime_utc": "2025-02-03T13:38:51.632Z",
"real_date": {
"date": "2025-02-03T14:38:51",
"utc_date": "2025-02-03T13:38:51.621Z"
},
"location": {
"name": "Plateforme Béligneux",
"place_name": "150 Chemin De Derontet, 01360 Béligneux, France",
"display_place_name": "ZA 2b - 150 Chemin Du Dérontet, 01360 Béligneux, France",
"city": "Béligneux",
"zip": "01360",
"country_code": "FR",
"platform": {
"code": "BELIGNEUX",
"name": "Plateforme Béligneux"
}
}
},
"vehicle_account": {
"vehicle_account_no": "VA-VOL-20241212-00982",
"customer_references" : [
{
"key" : "customer_identification",
"value" : "ref-cust-vin-NMN291NZXHRZ91MSK"
},
{
"key" : "order",
"value" : "KJ948-EE409"
}
],
"logistics_status": "delivered",
},
"order": {
"read_url": "https://"
}
}
Ad hoc outgoing flow translator
The object contained in body can be an ad hoc object matching the specific needs of an existing API.
In this case, as with incoming flows at e4Cars, you should contact the e4Cars integration teams (integration@e4cars.com) to provide them with the body you wish to receive in the calls.
They will create an ad hoc translator that will be used when transmitting status updates to your APIs based on the outgoing OutgoingEvent information.
Date value
All date (IN or OUT) are Locale
Below is the list of values for the field vehicle_account.logistics_status
| Value | Description |
|---|---|
| in_transit | In transit: beginning of the collection transport |
| receipt | Received: end of the collection transport |
| in_delivery | In delivery: beginning of the distribution transport |
| delivered | Delivered: end of the distribution transport |
Below is the list of all valid outgoing date formats:
- YYYY-MM-DDTHH24:MI:SS
- YYYY-MM-DDTHH24:MI:SSZ
- YYYY-MM-DDTHH24:MI
- YYYY-MM-DDTHH24:MI:SS.ms
- YYYY-MM-DDTHH24:MI:SS.msZ
In the case of the standard flow, here is an example of the body structure:
JSON Body Example
{
"vin": "STA207LBX1REB9164",
"license_plate": null,
"event": {
"family": "order_execution",
"type": "trip_delivery_ended",
"creation_datetime_utc": "2025-02-03T13:38:51.632Z",
"real_date": {
"date": "2025-02-03T14:38:51",
"utc_date": "2025-02-03T13:38:51.621Z"
},
"location": {
"name": "Plateforme Béligneux",
"place_name": "150 Chemin De Derontet, 01360 Béligneux, France",
"display_place_name": "ZA 2b - 150 Chemin Du Dérontet, 01360 Béligneux, France",
"city": "Béligneux",
"zip": "01360",
"country_code": "FR",
"platform": {
"code": "BELIGNEUX",
"name": "Plateforme Béligneux"
}
}
},
"vehicle_account": {
"vehicle_account_no": "VA-VOL-20241212-00982",
"customer_references" : [
{
"key" : "customer_identification",
"value" : "ref-cust-vin-NMN291NZXHRZ91MSK"
},
{
"key" : "order",
"value" : "KJ948-EE409"
}
],
"logistics_status": "delivered",
},
"order": {
"read_url": "https://"
}
}
| Code | Description | Example Response |
|---|---|---|
| 200 | Success, the flow was transmitted correctly. | { "status": "success", "message": "Incoming flow transmitted successfully." } |
| 401 | Unauthorized, missing or invalid authentication. | { "status": "error", "message": "Unauthorized. Please authenticate." } |
| 403 | Forbidden, insufficient permissions. | { "status": "error", "message": "Forbidden. You do not have the necessary permissions to execute this flow." } |
| 400 | Bad request, invalid body or parameters. | { "status": "error", "message": "Invalid request." } |