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.
|
|
string
|
Optional
|
The address of the driver renting the vehicle.
| |
|
string
|
Optional
|
The birth date of the driver renting the vehicle.
| |
|
string
|
Optional
|
The country of the driver renting the vehicle.
| |
|
string
|
Optional
|
The email address of the driver renting the vehicle.
| |
|
string
|
Optional
|
The driver's license number.
| |
|
string
|
Optional
|
The expiration date of the driver's license.
| |
|
string
|
Required
|
The name of the driver renting the vehicle.
| |
|
string
|
Optional
|
The passport number of the driver renting the vehicle.
| |
|
string
|
Required
|
The phone number of the driver renting the vehicle.
| |
|
int
|
Optional
|
The rating of the driver renting the vehicle.
| |
|
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"
}