Managing rental contracts

This API provides functionality for managing vehicle rental contracts. With this API, you can start, update, stop rentals, as well as authenticate and generate tokens for authorization.
 

Authorization

To use the API, authentication is required with a Bearer token.

Getting an authorization token

Before sending requests, you need to obtain a token by generating it using the login and password for the admin panel.

Authorization example

Example request to generate a token:
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"
}'
Example response:
{
    "code": 0,
    "odo": "0",
    "message": "007898667a1b5711682399ea38a84f61"
}
You will receive a token in the response. Use it in the Authorization header for further requests.
Example header:
Authorization: Bearer 007898667a1b5711682399ea38a84f61
 

Main commands

To perform operations, specify the cmd parameter, which defines which operation you want to perform:
  • generate_token — get token for authorization
  • start— start vehicle rental
  • update — update rental details
  • stop — stop vehicle rental
 

Request parameters

All parameters are sent in JSON format.
  Parameter
  Type
  Required
  Description
  mva
  int
  Yes
  Numeric ID of the rented vehicle
  ra
  int
  Yes
  Rental agreement number
  plate_number
  string
  Yes
  Vehicle plate number
  driver_name
  string
  Yes
  Name of the driver renting the vehicle
  driver_phone
  string
  Yes
  Driver's phone number
  driver_passport
  string
  No
  Driver's passport
  driver_address
  string
  No
  Driver's address
  driver_license
  string
  No
  Driver's license number
  driver_license_exp
  string
  No
  Driver's license expiry date
  driver_email
  string
  No
  Driver's email address
  driver_birth_date
  string
  No
  Driver's birth date
  driver_sex
  string
  No
  Gender (m or f)
  driver_country
  string
  No
  Driver's country
  driver_rating
  int
  No
  Driver's rating
  ts_expected
  int
  Yes
  Expected rental start time (Unix timestamp)
  te_expected
  int
  Yes
  Expected rental end time (Unix timestamp)
  ts_real
  int
  No
  Actual rental start time (Unix timestamp)
  te_real
  int
  No
  Actual rental end time (Unix timestamp)
  start_location
  object
  Yes
  Rental start location (with latitude, longitude or address)
  end_location
  object
  Yes
  Rental end location (latitude, longitude or address)
  rate_code
  string
  No
  Rental rate code
  car_group_charged
  string
  No
  Vehicle group for charging
  checkout_branch
  string
  No
  Checkout branch
  mileage_limit
  int
  No
  Mileage limit
  cid
  string
  No
  Client ID (driver renting the vehicle)
 

Example requests

 

Start rental

curl --location --request POST 'https://adm.pilot-gps.africa/backend/app/contracts.php' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 007898667a1b5711682399ea38a84f61' \
--data-raw '{
    "cmd": "start",
    "mva": 111,
    "ra": 67890,
    "plate_number": "ABC123",
    "driver_name": "John Doe",
    "driver_phone": "123-456-7890",
    "ts_expected": 1644927600,
    "te_expected": 1644981600,
    "start_location": { "lat": 40.712776, "lon": -74.005974 },
    "car_group_charged": "Economy"
}'
Response
{
    "code": 0,
    "odo": "1233",
    "message": "Success"
}
The response includes:
  • code— response code
  • odo— odometer value
  • message— message with the request result
     

Update rental

curl --location --request POST 'https://adm.pilot-gps.africa/backend/app/contracts.php' \
--header 'Authorization: Bearer 007898667a1b5711682399ea38a84f61' \
--header 'Content-Type: application/json' \
--data-raw '{
    "cmd": "update",
    "ra": 67890,
    "plate_number": "ABC123",
    "driver_name": "John Doe",
    "driver_phone": "123-456-7890",
    "mileage_limit": 2000
}'
Response
{
    "code": 0,
    "odo": "1208607",
    "message": "Success"
}
 

Stop rental

curl --location --request POST 'https://adm.pilot-gps.africa/backend/app/contracts.php' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "cmd": "stop",
    "ra": 67890,
    "driver_rating": 4,
    "end_location": {"address": "Ilino 2c"}
}'
Response
{
    "code": 0,
    "odo": "1208607",
    "message": "Success"
}
 

Response and error codes

0— Operation successful
1— Vehicle not found
2— No changes to update
3— Rental agreement not found
4— Authentication error
5— Unknown error
6— Insufficient rights to perform operation
7— Contracts module not active
8— This rental agreement number is already in use by another account
9— Vehicle rented by another account
10— Vehicle not rented
11— Incorrect request
12— Invalid location parameter
13— This rental agreement number is used by another agent
14— Passport was provided, but driver's name not specified
15— Driver's name provided, but passport not specified
16— Driver not found with provided details
17— Driver details do not match previously saved data
18— Rental agreement with this number not found
19— This rental agreement has already ended
20— Vehicle already rented
21— Incorrect driver specified
22— Existing contract closed, new one created
500— Internal server error