Contracts API

Overview

This is the documentation for the Contracts API version 1.0.1. The API provides endpoints for managing contracts related to rental agreements, vehicles, drivers, and customers.

In the description of this documentation, https://adm.pilot-gps.africa/ is used as the base URL, you can use any other admin URL

Authentication

The API uses Token for authentication. To authenticate your requests, include the token in the Authorization header as a bearer token.

For authorization, the login and password that you use for the admin panel are used.

Header

Authorization: Bearer <your_token>

Example curl auth header

curl --location --request POST 'https://adm.pilot-gps.africa/backend/app/contracts.php' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer YOUR_TOKEN' \

API Endpoints

POST /contracts.php

This endpoint allows you to manage contracts by performing various operations such as stopping, starting, updating, authenticating, and generating tokens.

Request Parameters

Parameter	Type	Required	Description
car_group_charged	string	Optional	The car group charged for the rental.
cid	string	Optional	The customer ID of the driver renting the vehicle.
driver_address	string	Optional	The address of the driver renting the vehicle.
driver_birth_date	string	Optional	The birth date of the driver renting the vehicle.
driver_country	string	Optional	The country of the driver renting the vehicle.
driver_email	string	Optional	The email address of the driver renting the vehicle.
driver_license	string	Optional	The driver's license number.
driver_license_exp	string	Optional	The expiration date of the driver's license.
driver_name	string	Required	The name of the driver renting the vehicle.
driver_passport	string	Optional	The passport number of the driver renting the vehicle.
driver_phone	string	Required	The phone number of the driver renting the vehicle.
driver_rating	int	Optional	The rating of the driver renting the vehicle.
driver_sex	string	Optional	The gender of the driver renting the vehicle (m for male, w for female).
end_location	object	Required	The location where the rental ended. Object with lat, lon or address string. Check out branch
mileage_limit	int	Optional	The mileage limit for the rental agreement.
mva	int	Required	A numeric identifier for the vehicle being rented.
plate_number	int	Required	Vehicle plate number.
ra	int	Required	A numeric identifier for the rental agreement.
rate_code	string	Optional	The rate code for the rental agreement.
start_location	object	Required	The location where the rental started. Object with lat, lon or address string. Check in branch.
te_expected	int	Required	The expected end time of the rental in Unix timestamp format.
te_real	int	Optional	The actual end time of the rental in Unix timestamp format.
ts_expected	int	Required	The expected start time of the rental in Unix timestamp format.
ts_real	int	Optional	The actual start time of the rental in Unix timestamp format.

Request cmd parameters

Generate_token	Generate token for auth header in request
start	Start rent vehicle
update	Update rent vehicle
stop	Stop rent vehicle

Response

The response will contain the following fields:

Code	integer	Response code
message	string	Message
odo	string	Odometer value

Response codes:

Code	Description
0	Success
1	Vehicle not found
2	Nothing to update
3	Rental agreement not found
4	Authentication failed
5	Unknown error
6	No rights
7	Contract module not active
8	This Ra number used another account
9	Vehicle in rent another account
10	Vehicle not in rent
11	Bad request
12	Invalid location param
13	This RA used in another agent
14	Passed passport but did not pass name
15	Passed name but did not pass passport
16	Driver not found
17	Different driver
18	Not found contract with RA number
19	This contract already ended
20	Vehicle already rented
21	Different vehicle

Example response JSON

{

"code": 2,

"odo": "1208607",

"message": "Nothing to update"

}

Errors

In case of errors, the API will return a 500 status code along with a JSON message containing a string description of the error.

Swagger

https://adm.pilot-gps.africa /resources/swagger-contracts.yml Here you can view api via swagger file.

As an interface, this swager file can be run for example here:

https://editor.swagger.io/?_ga=2.32283837.2078627632.1681127699-1612985961.1680523574

Examples

Authorization example

For authorization, we need to generate a token in order to use it later in the request header. Prepare the username and password that you use to log in to the admin panel

Request:

curl --location --request GET 'https://adm.pilot-gps.africa/backend/app/contracts.php' \

--header 'Content-Type: application/json' \

--data-raw '{

"cmd": "generate_token",

"login": "YOUR LOGIN FOR ADMIN PANEL",

"password": "YOUR PASSWORD FOR ADMIN PANEL"

Response:

{

"code": 0,

"odo": "0",

"message": "007898667a1b5711682399ea38a84f61"

}

In the response you are interested in the line under the "message" key, use this line as a header for subsequent requests.

Start rent.

Request:

curl --location --request POST 'https://adm.pilot-gps.africa/backend/app/contracts.php' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer 0adc8ab35b7fc549155d28a872b2463f' \

--header 'Cookie: PHPSESSID=ksv22b2961qr3t5kpjuio2p6jh' \

--data-raw '{

"cmd": "start", // required

"mva": 111, // required

"ra": 67890, // required

"plate_number": "plateNumber", // required

"driver_name": "John Doe", // required

"driver_passport": "ABC123", // optional

"driver_phone": "123-456-7890", // required

"driver_address": "123 Main St", // optional

"driver_license": "XYZ789", // optional

"driver_license_exp": "2024-12-31", // optional

"driver_email": "johndoe@example.com", // optional

"driver_birth_date": "1985-01-01", // optional

"driver_sex": "m", // optional

"driver_country": "USA", // optional

"driver_rating": 4, // optional

"ts_real": 1644924000, // optional

"ts_expected": 1644927600, // required

"te_expected": 1644981600, // required

"start_location": { // optional

"lat": 40.712776,

"lon": -74.005974

"cid": "C12345", // optional

"rate_code": "R123", // optional

"car_group_charged": "Economy", // required

"checkout_branch": "ABC123", // optional

"mileage_limit": 1000 // optional

Response

{

"code": 0,

"odo": "1233",

"message": "Success"

}

Update rent.

Request:

--header 'Authorization: Bearer 0adc8ab35b7fc549155d28a872b2463f' \

--header 'Content-Type: application/json' \

--header 'Cookie: PHPSESSID=ksv22b2961qr3t5kpjuio2p6jh' \

--data-raw '{

"cmd": "update", // required

"mva": 111, // optional

"ra": 67890, // required

"plate_number": "plateNumber", // required

"driver_name": "John Doe", // optional

"driver_passport": "ABC123", // optional

"driver_phone": "123-456-7890", // optional

"driver_address": "123 Main St", // optional

"driver_license": "XYZ789", // optional

"driver_license_exp": "2024-12-31", // optional

"driver_email": "johndoe@example.com", // optional

"driver_birth_date": "1985-01-01", // optional

"driver_sex": "m", // optional

"driver_country": "USA", // optional

"driver_rating": 2, // optional

"ts_real": 1644924000, // optional

"ts_expected": 1644927600, // optional

"te_expected": 1644981600, // optional

"start_location": { // optional

"lat": 40.712776,

"lon": -74.005974

"cid": "C123456", // optional

"rate_code": "R123", // optional

"car_group_charged": "Economy", // optional

"checkout_branch": "ABC123", // optional

"mileage_limit": 2000 // optional

Response update rent

{

"code": 0,

"odo": "1208607",

"message": "Success"

}

Stop rent.

Request:

curl --location --request POST 'https://adm.pilot-gps.africa/backend/app/contracts.php' \

--header 'Authorization: Bearer 0adc8ab35b7fc549155d28a872b2463f' \

--header 'Content-Type: application/json' \

--header 'Cookie: PHPSESSID=ksv22b2961qr3t5kpjuio2p6jh' \

--data-raw '{

"cmd": "stop", // required

"ra": 67890, // required

"driver_rating": 4, // optional

"end_location": { // optional

"address": "Ilino 2c"

}

Stop rent response

{

"code": 0,

"odo": "1208607",

"message": "Success"

}