Vecore Development Kit

# API

The public API can be used to manage information at the organization level.

# Public API

# Authorization

Most endpoints use API keys for authorization. The key can be sent in the request header:

apikey:xxxxxxxxxxxx

Note

All API keys are issued through Vecore. See the Contact section for more details.

# Endpoints

The endpoints of the public API are described here: https://vecoreportal.com/api/doc/publicv3 (opens new window)

# Push endpoint

With the Vecore push mechanism, changes within the Vecore platform can be synchronized with external systems. You can provide Vercore with an endpoint on which you want to receive the notifications.

# Format

Notifications are forwarded as JSON objects. The object contains the following fields:

action

  • create
  • update
  • remove

type

  • reservation
  • user
  • car
  • location
  • damage
  • user_notification

data

  • The changed object. If the action is 'update', we will only send the changed fields of an object.

# Response

After the message has been successfully processed, it must be answered with status code 200. If another status code is returned, the message will be send again after 15 minutes. A message will be sent a maximum of 10 times.

# Enable HMAC signatures

To build your solution for verifying HMAC signatures, follow these steps:

# Step 1: Calculate the HMAC signature

Calculate an HMAC using:

  • The SHA256 function.
  • The body of the response.
  • The private key set for this endpoint.

# Step 2: Compare signatures

If the signature that you calculated in Step 1 matches the x-hmac-signature that you received in the header, you'll know that the notification was sent by Vecore and was not modified during transmission.

# Example objects

Example of a user_notification object:

{
   "action":"create",
   "type":"user_notification",
   "data":{
      "message":"De gebruiker voor u is waarschijnlijk niet op tijd terug. U heeft de mogelijkheid de reservering te be\u00ebindigen.",
      "message_id":"car_not_on_location",
      "user":{
         "id":3241,
         "username":"user@mail.nl"
      }
   }
}

Example of a reservation object:

{ 
   "action":"create",
   "type":"reservation",
   "data":{ 
      "id":6280,
      "begin_date":"1474270200",
      "end_date":"1474274700",
      "updated_at":null,
      "user":{ 
         "id":406,
         "username":"test@user.nl",
         "first_name":"Test",
         "last_name":"user",
         "phone_number":"0612345678",
         "zip_code":"3770 AJ",
         "street_number":"1",
         "plan_active_till":"1474243200",
         "is_private":true,
         "is_business":true,
         "create_date":"1474270117",
         "plan":[ 

         ],
         "credits_prive":null,
         "credits_business":null,
         "birth_date":"459561600",
         "plan_paid":true,
         "total_km":0,
         "total_fuel_consumption":0,
         "accepted_terms_conditions":null,
         "flag_score":0
      },
      "car":{ 
         "id":3018,
         "vin":"PPCDVZAAZED045530",
         "licence_plate":"552A9",
         "is_active":true,
         "cartype":{ 
            "id":1,
            "brand":"Volkswagen",
            "type":"UP!",
            "credits_hour":null,
            "credits_km":null,
            "image_name":"1.jpg",
            "tank_capacity":35
         },
         "location":{ 
            "id":44,
            "name":"Test Location",
            "adres":"Elementenstraat 25",
            "zip_code":"1014AR ",
            "city":"Amsterdam",
            "latitude":"51.826575",
            "longitude":"5.000155",
            "is_active":true,
            "image_name":null
         },
         "mileage":"0",
         "fuel_level":"0",
         "battery_voltage":"300",
         "last_speed":"0"
      },
      "create_date":"1474270212"
   }
}

# Example object handling

Example of notification object handling in php:


$body = file_get_contents('php://input');
$event_json = json_decode($body);
date_default_timezone_set('UTC');

new handleVecoreMessage($event_json);


/*
* This class handles a Vecore Message
*/
class handleVecoreMessage
{

	//constructor
	public function __construct($inputJson)
	{

		if(isset($inputJson->type)) {
			switch ($inputJson->type) {
				case 'reservation':
                            
                    if($inputJson->action == 'remove') {
                        //TODO: handle reservation remove
                    }elseif($inputJson->action == 'create') {
                        //TODO: handle new reservation 
                    }else{
                        //TODO: handle reservation update
                    }
										
					$statusCode = 200;
					break;
				default:
					break;
			}
		} else {
			echo 'type not found';
			$statusCode = 404;
		}

		http_response_code($statusCode);
	}


}