Get Started

we are going to help you to start and configure petroapp intigration by creating a copy of our documentntation and reports. Make sure you've read our directory structure articles before continuing.

base path/url :
https://app-stg.petroapp.app/webservice/

simply this is our main modules you need to make an awesome integration

Generate Api Key

you have to use your main company user data [username , password] to get your api key to start with our web service configuration

As you might see in the get_apiKey directory;

URL : https://app-stg.petroapp.app/webservice/get_apiKey
Header Request parameters: none
Method : POST
Paramaters/body :
username*: your_company_username
password*: your_company_password
description : to return your api key .
Notes: expires_in return in seconds

success return:

                  {
                    "success": true,
                    "message": "بترو اب يرحب بك",
                    "data": {
                        "api_key": "123123123123",
                        "token_type": "bearer",
                        "expires_in": 31536000
                    }
                  }

failure return:

{
  "success": false,
  "message": "بيانات المستخدم غير صحيحة",
  "data": ""
}

Refresh Token

As you might see in the refresh_token directory;

URL : https://app-stg.petroapp.app/webservice/refresh_token
Header Request parameters:
Authorization : Bearer your_api_token
Method : POST
Paramaters/body : None
description : to refresh your token.

success return:

{
  "success": true,
  "message": "بترو اب يرحب بك",
  "data": {
      "api_key": "123123123123",
      "token_type": "bearer",
      "expires_in": 31536000
  }
}

failure return:

{
  "success": false,
  "message": "بيانات المستخدم غير صحيحة",
  "data": ""
}

Vehicles

Here you will get all your vehicles

As you might see in the vehicles directory;

URL : https://app-stg.petroapp.app/webservice/vehicles?page=page_number
Paramaters/body :
plate : ( String ) Example [ X Y Z 2 0 2 0 ] Vehicle Plate Number Or Truck Structure Number
Header Request parameters:
Authorization : Bearer your_api_token
Method :GET

success return:

{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
        {
          "branch_name": "Branch test1",
          "arabic_plate_letter": "س س س",
          "english_plate_letter": "S S S",
          "english_plate_number": "9 0 9 6",
          "arabic_plate_number": "٩ ٠ ٩ ٦",
          "trip_number": "test-123",
          "consumption_method": "NULL",
          "consumption_type": "NULL",
          "max_consumption_by_rial": 0,
          "max_consumption_by_liters": 0,
          "current_consumption_by_rial": 0,
          "current_consumption_by_liters": null,
          "photo": null,
          "vehicle_available_days": "Sun,Mon,Tue,Wed,Thu,Fri,Sat",
          "brand": " Austin",
          "model": " Mini Cooper",
          "type": "معدات ثقيلة",
          "year": null,
          "other_one": null,
          "other_two": null,
          "other_three": null,
          "chassis_number": "A1234567",
          "odometer":"120000",
          "internal_number": null
        }
    ],
    "from": 1,
    "last_page": 52,
    "next_page_url": "https://app-stg.petroapp.app/webservice/vehicles?page=2",
    "path": "https://app-stg.petroapp.app/webservice/vehicles",
    "per_page": 1,
    "prev_page_url": null,
    "to": 1,
    "total": 52
  }
}

failure return:

{
  "message": "no data found",
  "success": true,
  "data": {
      "current_page": 1,
      "data": [],
      "from": null,
      "last_page": 0,
      "next_page_url": null,
      "path": "https://app-stg.petroapp.app/webservice/vehicles",
      "per_page": 10,
      "prev_page_url": null,
      "to": null,
      "total": 0
  }
}

insert Trip

Here you will add new trip to vehicle

As you might see in the insert_trip directory;

URL : https://app-stg.petroapp.app/webservice/insert_trip
Header Request parameters:
Authorization : Bearer your_api_token
Method: POST
Paramaters/body :
plate : ( String ) Example [ X Y Z 2 0 2 0 ] Vehicle Plate Number Or Truck Structure Number
trip_number: ( String ) your new trip number
max_trip_consumption_rial : ( double ) max trip consumption in saudi rial (SRA)
start_date : ( Date ) format exampl YYYY-mm-dd
end_date : ( Date ) format example YYYY-mm-dd

success return::

{ "success": true,"message":"trip has been inserted", "data": {}  }

failure return:

{ "success": false,"message":"error is occured", "data": {}  }

Increase vehicle consumption

Here you can update vehicle consumption

Note that ! vehicle will be not related with any trips and this endpoint used to only increase vehicle consumption value

As you might see in the increase_vehicle_consumption directory;

URL : https://app-stg.petroapp.app/webservice/increase_vehicle_consumption
Header Request parameters:
Authorization : Bearer your_api_token
Method: POST
Paramaters/body :
plate : ( String ) Example [ X Y Z 2 0 2 0 ] Vehicle Plate Number Or Truck Structure Number

current_consumption : ( double ) vehicle consumption in saudi rial (SRA)

success return::

{ "success": true,"message":"vehicle consumption has been increased", "data": {}  }

failure return:

{ "success": false,"message":"error is occured", "data": {}  }

Update Trip

Here you will add new trip to vehicle

As you might see in the update_trip directory;
To update current trip skip {trip_number}
if you want update a one of trip parameter just need to skip others parameters

URL : https://app-stg.petroapp.app/webservice/update_trip
Header Request parameters:
Authorization : Bearer your_api_token
Method: POST
Paramaters/body :
current_trip_number : ( String ) your old trip number
trip_number: ( String ) your new trip number
increase_trip_consumption : ( double ) To Increase current trip consumption and existed max trip consumption
reset : ( Boolean ) To reset trip current consumption to equal existed max trip consumption
if reset parameter is true increase_trip_consumption will equal NULL
trip_consumption : ( double ) To set trip consumption value and current consumption you needn't to send reset or increase_trip_consumption
start_date : ( Date ) format exampl YYYY-mm-dd
end_date : ( Date ) format example YYYY-mm-dd

success return::

{ "success": true,"message":"trip has been updated", "data": {}  }

failure return:

{ "success": false,"message":"error is occured", "data": {}  }

Updated trips list

Here you will get updated trips had consumed with vehicle plate number

page limit with 10 records to get second records send parameter page=2... pagination structure

As you might see in the updated_trips directory;

URL : https://app-stg.petroapp.app/webservice/updated_trips
Header Request parameters:
Authorization : Bearer your_api_token
Method: GET
Paramaters/body :
date_from : ( Date ) format exampl YYYY-mm-dd H:i:s
date_to : ( Date ) format example YYYY-mm-dd H:i:s
status : ( Boolean ) true : active / false : inactive

success return::

{
                    "success": true,
                    "data": [
                        {
                            "trip_number": "81002",
                            "trip_start": "2022-05-31 02:00:00",
                            "trip_end": "2022-06-01 02:00:00",
                            "trip_consumption": 500,
                            "consumed": 100,
                            "remaining_balance": 400,
                            "active": "active",
                            "updated_at": "2022-05-31T07:49:25.000000Z",
                            "vehicle": "H H H - 9 9 9 9"
                        }
                    ]
                }

failure return:
```
{ "success": false,"data": {}  }
```

Assign vehicle to trip

Here you will assign trip to vehicle

As you might see in the assign_vehicle_to_trip directory;

URL : https://app-stg.petroapp.app/webservice/assign_vehicle_to_trip
Header Request parameters:
Authorization : Bearer your_api_token
Method: POST
Paramaters/body :
trip_number : ( STRING ) your trip number
plate: ( STRING ) Vehicle plate

success return::

{ "success": true,"message":"vehicle now can using this trip", "data": {}  }

failure return:

{ "success": false,"message":"this vehicle is not exist", "data": {}  }

Remove vehicle from trip

Here you will remove vehicle from trip

As you might see in the remove_vehicle_from_trip directory;

URL : https://app-stg.petroapp.app/webservice/remove_vehicle_from_trip
Header Request parameters:
Authorization : Bearer your_api_token
Method: POST
Paramaters/body :
trip_number : ( STRING ) your trip number
plate: ( STRING ) Vehicle plate

Note : vehicle consumption method will changed to open then (max_consumption , current_consumption )
values will be ( 0 SAR )

success return::

{ "success": true,"message":"vehicle now can not using this trip", "data": {}  }

failure return:

{ "success": false,"message":"this vehicle is not exist", "data": {}  }

Active Trip

To active trip use this endpoint

As you might see in the active_trip directory;

URL : https://app-stg.petroapp.app/webservice/active_trip/trip_number
Header Request parameters:
Authorization : Bearer your_api_token
Method: POST

success return::

{ "success": true,"message":"trip has been active", "data": {}  }

failure return:

{ "success": false,"message":"trip not found", "data": {}  }

Deactivate Trip

To stop trip use this endpoint

As you might see in the deactivate_trip directory;

URL : https://app-stg.petroapp.app/webservice/deactivate_trip/trip_number
Header Request parameters:
Authorization : Bearer your_api_token
Method: POST

success return::

{ "success": true,"message":"trip has been deactivate", "data": {}  }

failure return:

{ "success": false,"message":"trip not found", "data": {}  }

Trip status log

trip log to check who`s activate or deactivate trip

As you might see in the trip_status_logs directory;

URL : https://app-stg.petroapp.app/webservice/trip_status_logs
Header Request parameters:
Authorization : Bearer your_api_token
Method: GET

success return::

{
    "success": true,
    "data": {
        "current_page": 1,
        "data": [
            {
                "trip_consumption": 1,
                "current_consumption": 1,
                "trip_number": "75002",
                "username": "app",
                "status": 0
            },
            {
                "trip_consumption": 1,
                "current_consumption": 1,
                "trip_number": "75002",
                "username": "app",
                "status": 1
            }
        ],
        "first_page_url": "http://127.0.0.1:9999/webservice/trip_status_logs?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://127.0.0.1:9999/webservice/trip_status_logs?page=1",
        "links": [
            {
                "url": null,
                "label": "pagination.previous",
                "active": false
            },
            {
                "url": "http://127.0.0.1:9999/webservice/trip_status_logs?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "pagination.next",
                "active": false
            }
        ],
        "next_page_url": null,
        "path": "http://127.0.0.1:9999/webservice/trip_status_logs",
        "per_page": 10,
        "prev_page_url": null,
        "to": 2,
        "total": 2
    }
}

failure return:

{ "success": false,"message":"trip not found", "data": {}  }

Vehicles Trip Log

Here you will get all your vehicles trip log

As you might see in the vehicles_trip_log_data directory;

URL : https://app-stg.petroapp.app/webservice/vehicles_trip_log_data?page=page_number
Paramaters/body :
trip_number: ( String ) trip number
Header Request parameters:
Authorization : Bearer your_api_token
Method:GET

success return:

{
  "success": true,
  "data": {
      "current_page": 1,
      "data": [
          {
            "branch_name": "Branch test1",
            "plate_letter_arabic": "ر ر ر",
            "plate_letter_english": "R R R",
            "structure_number": null,
            "plate_arabic_number": "۰ ۰ ۰ ۰",
            "english_plate_number": "0 0 0 0",
            "trip_number": "5dc4ce0d8f92d",
            "trip_consumption_by_rial": 100,
            "current_consumption_by_rial": 80,
            "trip_start_date": "2019-09-08 00:00:00",
            "trip_end_date": "2019-11-09 00:00:00",
            "inserted_at": null,
            "fuel_type": "91"
          }
      ],
      "from": 1,
      "last_page": 1,
      "next_page_url": "http://localhost/petroappwebprod/webservice/vehicles_trip_log_date?page=2",
      "path": "http://localhost/petroappwebprod/webservice/vehicles_trip_log_date",
      "per_page": 10,
      "prev_page_url": null,
      "to": 1,
      "total": 1
  }
}

failure return:

{
  "message": "no data found",
  "success": true,
  "data": {
      "current_page": 1,
      "data": [],
      "from": null,
      "last_page": 0,
      "next_page_url": null,
      "path": "https://app-stg.petroapp.app/webservice/vehicles_trip_log_date",
      "per_page": 10,
      "prev_page_url": null,
      "to": null,
      "total": 0
  }
}

Get Bills

Here you can get your company bills with filter inputs

As you might see in the bills directory;

Language parameters : ar || en
URL : https://app-stg.petroapp.app/webservice/bills?page=page_number&from=YYYY-mm-dd&to=YYYY-mm-dd&branch_name=your_branch_name&lang=en
Header Request parameters:
Authorization : Bearer your_api_token
Method : GET
parameters:
from : :( Date ) format example YYYY-mm-dd
to :( Date ) format example YYYY-mm-dd
branch_name : ( String ) Example: branch test

Successfuly Response:

{
    "success": true,
    "data": {
        "current_page": 1,
        "data": [
            {
              "bill_date": "2019-10-09 12:55:33",
              "trip_number": null,
              "payment_method": 1,
              "billDate": "2019-10-09 12:55:33",
              "status": 0,
              "branch_name": "Branch test1",
              "station_name": "حساب تجريبي",
              "station_lat": 21.63234578000000141173586598597466945648193359375,
              "station_lng": 48.62287828000000189376805792562663555145263671875,
              "delegate_name": null,
              "plate_letter": null,
              "plate_snum": null,
              "cost": 50.5,
              "num_of_liters": 107.4470000000000027284841053187847137451171875,
              "internal_number": null,
              "structure_number": null,
              "city": " طريف",
              "district": " الورود",
              "payment_method_text": "نقدى",
              "odometer":"120000"
            }
        ],
        "from": 1,
        "last_page": 1,
        "next_page_url": https://pre.petroapp.com.sa/webservice/bills?page=2,
        "path": "https://pre.petroapp.com.sa/webservice/bills",
        "per_page": 10,
        "prev_page_url": null,
        "to": 3,
        "total": 3
    }
}

Get Bills For Trips

Here you will your company bills with trip number input

As you might see in the bills directory;

URL : https://pre.petroapp.com.sa/webservice/bills?page=page_number&trip_number=trip_number
Header Request parameters:
Authorization : Bearer your_api_token
Method :GET
parameters:
trip_number: (String)

Successfuly Response:

{
  "success": true,
  "data": {
      "current_page": 1,
      "data": [
          {
            "bill_date": "2019-10-09 12:55:33",
            "trip_number": 123123,
            "payment_method": 1,
            "billDate": "2019-10-09 12:55:33",
            "status": 0,
            "branch_name": "Branch test1",
            "station_name": "حساب تجريبي",
            "station_lat": 21.63234578000000141173586598597466945648193359375,
            "station_lng": 48.62287828000000189376805792562663555145263671875,
            "delegate_name": null,
            "plate_letter": null,
            "plate_snum": null,
            "cost": 50.5,
            "num_of_liters": 107.4470000000000027284841053187847137451171875,
            "internal_number": null,
            "structure_number": null,
            "city": " طريف",
            "district": " الورود",
            "payment_method_text": "نقدى",
            "odometer":"120000"
          }
      ],
      "from": 1,
      "last_page": 1,
      "next_page_url": "https://pre.petroapp.com.sa/webservice/bills?page2",
      "path": "https://pre.petroapp.com.sa/webservice/bills",
      "per_page": 10,
      "prev_page_url": null,
      "to": 3,
      "total": 3
  }
}

PetroApp Locations

Here you will get all petroapp locations

As you might see in the petroapp_locations directory;

URL : https://pre.petroapp.com.sa/webservice/petroapp_locations?page=page_number
Header Request parameters:
Authorization : Bearer your_api_token
Method : GET
Params: Response with station title , lat / lng , station services

success return locations:

{
  "request": null,
      "locs": [
        {
      "station_name": "adwa elezz",
      "lat": 24.551790199999999231295078061521053314208984375,
      "lng": 46.6297075199999966343966661952435970306396484375,
      "id": 8,
      "service": [
          {
              "service_name": "صيانة سيارات"
          },
          {
              "service_name": "بنشر"
          },
          {
              "service_name": "مغسلة سيارات"
          },
          {
              "service_name": "سوبر ماركت"
          },
          {
              "service_name": "صراف الي"
          },
          {
              "service_name": "كوفي شوب"
          },
          {
              "service_name": "مسجد"
          },
          {
              "service_name": "غيار زيت"
          }
      ],
      "petrol_prices": [
          {
              "id": 1,
              "fuel_type": "91"
          },
          {
              "id": 3,
              "fuel_type": "ديزل"
          }
      ],
      "diesel": "yes"
  },
  ]
}

PetroApp Locations Filter

As you might see in the petroapp_locations directory;

URL : https://pre.petroapp.com.sa/webservice/petroapp_locations?page=page_number&search_request=lat,lng
OR : https://pre.petroapp.com.sa/webservice/petroapp_locations?page=page_number&search_request=station_name
Header Request parameters:
Authorization : Bearer your_api_token
Method:GET
Paramaters:
search_request: lat,lng || (String) station_name || (String) station_services
search_request with latitude longitude type lat,lng the same this way 24.55179019999,24.55179019999
search_request with title type any String title and if exist you will get station data , return with request letter

{
    "lat": "24.551790199999999231295078061521053314208984375",
    "lng": "46.6297075199999966343966661952435970306396484375",
    "request": "24.551790199999999231295078061521053314208984375,46.6297075199999966343966661952435970306396484375",
    "locs": [
        {
    "station_name": "adwa elezz",
    "lat": 24.551790199999999231295078061521053314208984375,
    "lng": 46.6297075199999966343966661952435970306396484375,
    "id": 8,
    "service": [
        {
            "service_name": "صيانة سيارات"
        },
        {
            "service_name": "بنشر"
        },
        {
            "service_name": "مغسلة سيارات"
        },
        {
            "service_name": "سوبر ماركت"
        },
        {
            "service_name": "صراف الي"
        },
        {
            "service_name": "كوفي شوب"
        },
        {
            "service_name": "مسجد"
        },
        {
            "service_name": "غيار زيت"
        }
    ],
    "petrol_prices": [
        {
            "id": 1,
            "fuel_type": "91"
        },
        {
            "id": 3,
            "fuel_type": "ديزل"
        }
    ],
    "diesel": "yes"
},
    ]
}