Introduction V2

Last updated: 07-12-2017
Version: V2

The CarPAl API is a RESTful web service for developers and integrations to programmatically interact with CarPal’s data and real-time delivery management and analytics functionality.

Every bit of data exchanged between clients and the API is JSON over HTTPS.

In this document you will find a list of available integrations.

The following endpoint has to be used for all API calls:

Live: https://api.carpal.me
Sandbox: https://api-sandbox.carpal.me

Products

CarPal currently offers two products that will need to be triggered in certain endpoints through a product_type_id:

  1. CarPal Service (1)
  2. CarPal Fleet (3)

Every new customer is per default assigned to ‘CarPal Service’ and you can not trigger a product_type_id that is not assigned to you.

Support

Kindly contact us via email for API support or if you have suggestions or found a bug: supportsg@carpal.me or submit a request through our contact form.

Back To Top

Authentication

Every endpoint requires you to authenticate with a JSON token and you will have to pass a header to every request:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjEsImlzcyI6Imh0dHBzOlwvXC9hcGkuY2FycGFsLm1lXC92MlwvYXV0aGVudGljYXRlIiwiaWF0IjoxNDgxNTI2MTkwLCJleHAiOjE0OTcyOTQxOTAsIm5iZiI6MTQ4MTUyNjE5MCwianRpIjoiZTZmYjdmZWQ4ZmE2YjZmMDhjZDZhMzc1YjdhNmQ4ZmUifQ.9SFVor8Qlq__EvdmIcQuEOsKZJqDXxOYmaSMIZWimeE

The token can be retrieved with your user account on POST url:

/v2/authenticate

If you are working on the Sandbox you can use the following account:

email: demo@carpal.me
password: carpaldemo

Note that this account has product_type_id: 1 (CarPal Service)

If you want to test with CarPal Fleet use the following credentials:

email: transaction@carpal.me
password: transactioncustomer

Required fields:

  • email
  • password

Return Success:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjk3OTYsImlzcyI6Imh0dHBzOlwvXC9hcGkuY2FycGFsLm1lXC92MlwvYXV0aGVudGljYXRlIiwiaWF0IjoxNDg0NjY3NTg0LCJleHAiOjE1MDA0MzU1ODQsIm5iZiI6MTQ4NDY2NzU4NCwianRpIjoiMmYxYTVjMGQzMThjN2FjNTIyZTNlNmZjMGY3Mjg5NzkifQ.YMYv5XlhyV0biedUHx8XpPPYkltFMfdyoEU-yDwD4LI"
}

Expires: 1 hour (after which you will have to re-validate through this endpoint)

Return Error:

  • invalid_credentials
  • could_not_create_token

You can create your ‘Live’ (token expires after 182 days) account by registering via customer.carpal.me/customer/register

Back To Top

Throttling

You may not perform more than 10 requests per second across all of your organization’s accounts.

If you exceed 10 req/s, you will first receive an error. Failure to slow down your request rate may result in a temporary ban.

Should you require a higher request rate, do let us know by contacting support and we will do everything we can to accommodate your needs.

Back To Top

Identities

Identities represent the top-most entity on CarPal. Employees, customers, drivers, orders and vendors all belong to an identity. Identities are always linked to a country and reflect default settings as currency, timezone and country code.

You can retrieve a list of available identities through the Get Identities endpoint:
Retrieve a list of identities

POST url:

/v2/identity/get

Note: identity_id’s are required for various API actions.

Return success:

1: Success

{
  "identities": [
    {
      "id": 1,
      "Addresses_Id": 1,
      "created_at": "2015-11-16 07:24:07",
      "updated_at": "2015-11-16 07:24:07",
      "Currencies_Id": 1,
      "Countries_Id": 1,
      "Identities_details_Id": 1,
      "country_code": {
        "id": 1,
        "country_code": "SG",
        "created_at": "2015-11-16 07:24:07",
        "updated_at": "2015-11-16 07:24:07"
      },
      "currency": {
        "id": 1,
        "Countries_Id": 1,
        "currency": "SGD",
        "created_at": "2015-11-16 07:24:07",
        "updated_at": "2015-11-16 07:24:07"
      },
      "identity_detail": {
        "id": 1,
        "name": "Singapore",
        "phone": null,
        "identity_support_email": "supportsg@carpal.me",
        "created_at": "2015-11-16 07:24:07",
        "updated_at": "2015-11-16 07:24:07",
        "legal_name": "CarPal SG Pte Ltd",
        "website": "www.carpal.me",
        "company_registration_number": "201502058E",
        "timezone": "Singapore"
      }
    },
    {
      "id": 2,
      "Addresses_Id": 17615,
      "created_at": "-0001-11-30 00:00:00",
      "updated_at": "-0001-11-30 00:00:00",
      "Currencies_Id": 2,
      "Countries_Id": 3,
      "Identities_details_Id": 2,
      "country_code": {
        "id": 3,
        "country_code": "MY",
        "created_at": "-0001-11-30 00:00:00",
        "updated_at": "-0001-11-30 00:00:00"
      },
      "currency": {
        "id": 2,
        "Countries_Id": 3,
        "currency": "MYR",
        "created_at": "-0001-11-30 00:00:00",
        "updated_at": "-0001-11-30 00:00:00"
      },
      "identity_detail": {
        "id": 2,
        "name": "Kuala Lumpur",
        "phone": null,
        "identity_support_email": null,
        "created_at": "-0001-11-30 00:00:00",
        "updated_at": "-0001-11-30 00:00:00",
        "legal_name": "CarPal SG Pte Ltd",
        "website": "www.carpal.me",
        "company_registration_number": null,
        "timezone": "Singapore"
      }
    },
    {
      "id": 3,
      "Addresses_Id": 1,
      "created_at": "-0001-11-30 00:00:00",
      "updated_at": "-0001-11-30 00:00:00",
      "Currencies_Id": 1,
      "Countries_Id": 4,
      "Identities_details_Id": 3,
      "country_code": {
        "id": 4,
        "country_code": "PH",
        "created_at": "-0001-11-30 00:00:00",
        "updated_at": "-0001-11-30 00:00:00"
      },
      "currency": {
        "id": 1,
        "Countries_Id": 1,
        "currency": "SGD",
        "created_at": "2015-11-16 07:24:07",
        "updated_at": "2015-11-16 07:24:07"
      },
      "identity_detail": {
        "id": 3,
        "name": "Manila",
        "phone": null,
        "identity_support_email": null,
        "created_at": "-0001-11-30 00:00:00",
        "updated_at": "-0001-11-30 00:00:00",
        "legal_name": "CarPal SG Pte Ltd",
        "website": "www.carpal.me",
        "company_registration_number": null,
        "timezone": "Singapore"
      }
    },
    {
      "id": 4,
      "Addresses_Id": 1,
      "created_at": "-0001-11-30 00:00:00",
      "updated_at": "-0001-11-30 00:00:00",
      "Currencies_Id": 6,
      "Countries_Id": 5,
      "Identities_details_Id": 4,
      "country_code": {
        "id": 5,
        "country_code": "ID",
        "created_at": "-0001-11-30 00:00:00",
        "updated_at": "-0001-11-30 00:00:00"
      },
      "currency": {
        "id": 6,
        "Countries_Id": 5,
        "currency": "IDR",
        "created_at": "-0001-11-30 00:00:00",
        "updated_at": "-0001-11-30 00:00:00"
      },
      "identity_detail": {
        "id": 4,
        "name": "Jakarta",
        "phone": null,
        "identity_support_email": null,
        "created_at": "-0001-11-30 00:00:00",
        "updated_at": "-0001-11-30 00:00:00",
        "legal_name": "CarPal SG Pte Ltd",
        "website": "www.carpal.me",
        "company_registration_number": null,
        "timezone": "Singapore"
      }
    },
    {
      "id": 5,
      "Addresses_Id": 1,
      "created_at": "-0001-11-30 00:00:00",
      "updated_at": "-0001-11-30 00:00:00",
      "Currencies_Id": 7,
      "Countries_Id": 6,
      "Identities_details_Id": 5,
      "country_code": {
        "id": 6,
        "country_code": "HK",
        "created_at": "-0001-11-30 00:00:00",
        "updated_at": "-0001-11-30 00:00:00"
      },
      "currency": {
        "id": 7,
        "Countries_Id": 6,
        "currency": "HKD",
        "created_at": "-0001-11-30 00:00:00",
        "updated_at": "-0001-11-30 00:00:00"
      },
      "identity_detail": {
        "id": 5,
        "name": "Hong Kong",
        "phone": null,
        "identity_support_email": null,
        "created_at": "-0001-11-30 00:00:00",
        "updated_at": "-0001-11-30 00:00:00",
        "legal_name": null,
        "website": null,
        "company_registration_number": null,
        "timezone": "Singapore"
      }
    }
  ],
  "code": 1
}

Back To Top

User

Every actor (employee, customer, vendor, driver) on the CarPal API ultimately has a user to perform an action.

To retrieve the details of your user object you will have to use the following endpoint.
POST url:

/v2/user/show

There are no required fields, as we will retrieve the user object based on your Authorization header.

Note: you can also find the associated promo code, customer, vendor, employee and driver through this API.

Return success:

  • User not found (1)
  • Succes (2)
{
  "user_id": 1,
  "first_name": "test12",
  "last_name": "test1234",
  "email": "demo@carpal.me",
  "customer": {
    "id": 1,
    "created_at": "2017-01-18 05:11:30",
    "updated_at": "2017-01-18 05:11:30",
    "Customer_details_Id": 1,
    "timezone": "Singapore",
    "customer_details": {
      "id": 1,
      "company_name": null,
      "company_phone": null,
      "company_vat_number": null,
      "created_at": "2017-01-18 05:11:30",
      "updated_at": "2017-01-18 05:11:30"
    },
    "customer_identity": {
      "id": 1,
      "Customers_Id": 1,
      "Identity_Id": 1,
      "created_at": "2017-01-18 05:11:31",
      "updated_at": "2017-01-18 05:11:31",
      "identity_details": {
        "id": 1,
        "Addresses_Id": 1,
        "created_at": "2017-01-18 05:11:31",
        "updated_at": "2017-01-18 05:11:31",
        "Currencies_Id": 1,
        "Countries_Id": 1,
        "Identities_details_Id": 1,
        "country_code": {
          "id": 1,
          "country_code": "SG",
          "created_at": "2017-01-18 05:11:30",
          "updated_at": "2017-01-18 05:11:30"
        },
        "identity_detail": {
          "id": 1,
          "name": "Singapore",
          "phone": null,
          "identity_support_email": null,
          "created_at": "2017-01-18 05:11:31",
          "updated_at": "2017-01-18 05:11:31",
          "legal_name": "CarPal SG Pte Ltd",
          "website": "www.carpal.me",
          "company_registration_number": "201502058E",
          "timezone": "Singapore"
        }
      }
    },
    "addresses": [
      {
        "id": 7,
        "Addresses_Id": 1000000051,
        "deleted_at": null,
        "Customers_Id": 1,
        "address": {
          "id": 1000000051,
          "address_line1": null,
          "address_line2": null,
          "streetname": null,
          "address": "Aft GE Life Ctr, Singapore",
          "house_number": null,
          "appartment_number": null,
          "postalcode": null,
          "lat": "1.3170954",
          "long": "103.9029515",
          "google_place_id": null,
          "state_province": null,
          "city": null,
          "area": null,
          "Countries_Id": 1,
          "Address_types_Id": 9,
          "created_at": "2017-01-18 06:29:51",
          "updated_at": "2017-01-18 06:29:51",
          "building_name": "aaaaa",
          "unit_number": "bbbb"
        }
      },
      {
        "id": 8,
        "Addresses_Id": 1000000052,
        "deleted_at": null,
        "Customers_Id": 1,
        "address": {
          "id": 1000000052,
          "address_line1": null,
          "address_line2": null,
          "streetname": null,
          "address": "Aft GE Life Ctr, Singapore",
          "house_number": null,
          "appartment_number": null,
          "postalcode": null,
          "lat": "1.3170954",
          "long": "103.9029515",
          "google_place_id": null,
          "state_province": null,
          "city": null,
          "area": null,
          "Countries_Id": 1,
          "Address_types_Id": 9,
          "created_at": "2017-01-18 06:29:52",
          "updated_at": "2017-01-18 06:29:52",
          "building_name": "aaaaa",
          "unit_number": "bbbb"
        }
      },
      {
        "id": 9,
        "Addresses_Id": 1000000053,
        "deleted_at": null,
        "Customers_Id": 1,
        "address": {
          "id": 1000000053,
          "address_line1": null,
          "address_line2": null,
          "streetname": null,
          "address": "Aft GE Life Ctr, Singapore",
          "house_number": null,
          "appartment_number": null,
          "postalcode": null,
          "lat": "1.3170954",
          "long": "103.9029515",
          "google_place_id": null,
          "state_province": null,
          "city": null,
          "area": null,
          "Countries_Id": 1,
          "Address_types_Id": 9,
          "created_at": "2017-01-18 06:29:52",
          "updated_at": "2017-01-18 06:29:52",
          "building_name": "aaaaa",
          "unit_number": "bbbb"
        }
      },
      {
        "id": 10,
        "Addresses_Id": 1000000054,
        "deleted_at": null,
        "Customers_Id": 1,
        "address": {
          "id": 1000000054,
          "address_line1": null,
          "address_line2": null,
          "streetname": null,
          "address": "Aft GE Life Ctr, Singapore",
          "house_number": null,
          "appartment_number": null,
          "postalcode": null,
          "lat": "1.3170954",
          "long": "103.9029515",
          "google_place_id": null,
          "state_province": null,
          "city": null,
          "area": null,
          "Countries_Id": 1,
          "Address_types_Id": 9,
          "created_at": "2017-01-18 06:29:53",
          "updated_at": "2017-01-18 06:29:53",
          "building_name": "aaaaa",
          "unit_number": "bbbb"
        }
      }
    ],
    "customer_product_types": [],
    "customer_credits": {
      "id": 1,
      "Customers_Id": 1,
      "credits": 99922.12,
      "created_at": "2017-01-18 05:11:31",
      "updated_at": "2017-01-18 06:29:48"
    }
  },
  "employee": {
    "id": 1,
    "Users_Id": 1,
    "created_at": "2017-01-18 05:11:30",
    "updated_at": "2017-01-18 05:11:30",
    "timezone": "Singapore",
    "employee_identity": {
      "id": 1,
      "Identity_Id": 1,
      "Employees_Id": 1,
      "created_at": "2017-01-18 05:11:30",
      "updated_at": "2017-01-18 05:11:30",
      "identity_details": {
        "id": 1,
        "Addresses_Id": 1,
        "created_at": "2017-01-18 05:11:31",
        "updated_at": "2017-01-18 05:11:31",
        "Currencies_Id": 1,
        "Countries_Id": 1,
        "Identities_details_Id": 1,
        "identity_detail": {
          "id": 1,
          "name": "Singapore",
          "phone": null,
          "identity_support_email": null,
          "created_at": "2017-01-18 05:11:31",
          "updated_at": "2017-01-18 05:11:31",
          "legal_name": "CarPal SG Pte Ltd",
          "website": "www.carpal.me",
          "company_registration_number": "201502058E",
          "timezone": "Singapore"
        },
        "country_code": {
          "id": 1,
          "country_code": "SG",
          "created_at": "2017-01-18 05:11:30",
          "updated_at": "2017-01-18 05:11:30"
        }
      }
    }
  },
  "driver": {
    "id": 1,
    "Drivers_details_Id": 1,
    "Users_Id": 1,
    "Drivers_status_Id": 1,
    "Drivers_products_types_Id": 2,
    "online": 1,
    "details": {
      "id": 1,
      "Vehicle_Id": null,
      "Drivers_bank_Id": null,
      "Drivers_interviews_Id": null,
      "id_number": null,
      "vehicle": null
    },
    "identity": {
      "id": 1,
      "Drivers_Id": 1,
      "Identity_Id": 1,
      "created_at": "2017-01-18 05:11:31",
      "updated_at": "2017-01-18 05:11:31",
      "identity_details": {
        "id": 1,
        "Addresses_Id": 1,
        "created_at": "2017-01-18 05:11:31",
        "updated_at": "2017-01-18 05:11:31",
        "Currencies_Id": 1,
        "Countries_Id": 1,
        "Identities_details_Id": 1,
        "country_code": {
          "id": 1,
          "country_code": "SG",
          "created_at": "2017-01-18 05:11:30",
          "updated_at": "2017-01-18 05:11:30"
        }
      }
    },
    "options": []
  },
  "phone": "123456",
  "birthday": null,
  "address": null,
  "roles": [
    {
      "user_id": 1,
      "role_id": 1
    },
    {
      "user_id": 1,
      "role_id": 2
    }
  ],
  "subroles": [
    {
      "id": 1,
      "Users_Id": 1,
      "Sub_roles_Id": 1,
      "created_at": "2017-01-18 05:11:30",
      "updated_at": "2017-01-18 05:11:30",
      "details": {
        "id": 1,
        "name": "Super Admin",
        "description": "Highest level admin",
        "Roles_Id": 1,
        "created_at": "2017-01-18 05:11:30",
        "updated_at": "2017-01-18 05:11:30",
        "role": {
          "id": 1,
          "name": "admin",
          "display_name": null,
          "description": null,
          "created_at": "2017-01-18 05:11:30",
          "updated_at": "2017-01-18 05:11:30"
        }
      }
    },
    {
      "id": 2,
      "Users_Id": 1,
      "Sub_roles_Id": 5,
      "created_at": "2017-01-18 05:11:30",
      "updated_at": "2017-01-18 05:11:30",
      "details": {
        "id": 5,
        "name": "Service Customer",
        "description": "Customer that uses the system on a service model",
        "Roles_Id": 2,
        "created_at": "2017-01-18 05:11:30",
        "updated_at": "2017-01-18 05:11:30",
        "role": {
          "id": 2,
          "name": "customer",
          "display_name": null,
          "description": null,
          "created_at": "2017-01-18 05:11:30",
          "updated_at": "2017-01-18 05:11:30"
        }
      }
    }
  ],
  "code": 2
}

Back To Top

Rates (CarPal Fleet)

CarPal Fleet customers can choose to set their own rates per group. CarPal Service customers do not have the option to set their own rates.

Rates are calculated on different elements:

  1. Pickup Rate
  2. Additional Location Rate
  3. Discount Codes
  4. Kilometer Rate (and kilometer limit)
  5. Driver Rate (percentage)
  6. Order Options (and rates)
  7. Product Services (and rates)

You will have to set rates for every step and assign them to a transaction_group_id. Then when you create a new order later on, you can select the group and subsequently the rate that you want to use for that specific order. We will discuss every element below.

Work in progress.

 

Back To Top

Get Delivery Quote

Below we will go through the steps you have to take to create a successful order on the CarPal API. Here is a high-level overview of the 3 steps you will have to take:

  • Request a Quote
  • Place an Order
  • Make the Payment

This endpoint is integrated with the Google Geocoding API and will validate your input accordingly.

POST url:

/v2/quote/get

Fields:

  • ‘identity_id’ => ‘required|numeric’
  • ‘pickup_location’ => ‘required’,
  • ‘delivery_locations’ => ‘required’,
  • ‘pickup_date’ => ‘required|date_format:d-m-Y’,
  • ‘pickup_timing’ => ‘required|H:i’ (i.e. 13:00 or 09.00)
  • ‘quote_product_id’ => ‘numeric|required’
  • ‘transaction_group_id’ => ‘numeric|optional’ (note that transaction_group_id is required when requesting for CarPal SaaS (product_type_id 3)
  • ‘product_service_id’ => ‘numeric|optional’
  • ‘transaction_sub_customer_id’ => ‘numeric|optional’

Note: the actual pickup_timing should be at least 60 minutes away from the moment you create the order.

We will now discuss the above mandatory fields and further optional fields:

identity_id

  • Singapore (1)

See above under Entities on how to retrieve the identity_id (the service is available in multiple countries).

quote_product_id

The quote_product_id is used to identify the product that was used to place the quote. We use this quote_product_id to for example define the payment method.

  • CarPal Service (1)
  • CarPal SaaS (3)

transaction_group_id

This field is required if the quote_product_id is a CarPal Fleet Product Type Id which evaluates to the value of 3.

Please create and retrieve your transaction groups here: https://www.carpal.me/developers/api-v2/#document-17

product_service_id

Note that the following services are only available if you are using ‘Carpal Service’ quote_product_type_id.

Important! If you are using CarPal SaaS, you will have to set-up you own product_services. (note that a product_service is required when requesting for CarPal SaaS (product_type_id 3) and you can only use the product_service_id that belongs to the same transaction_group_id. Please note that we currently do not have an endpoint to manage the product service, kindly set these up directly through customer.carpal.me.

For identity_id = 1 (Singapore):

  • 1KG (30*30*25cm) (motorcycle) (1)
  • 10KG (100*50*50cm) (car) (2)
  • 20kg (car) (3)
  • 30KG (car) (4)
  • 40KG (car) (5)
  • 50KG (car) (6)
  • VAN (7)

pickup_location

  $pickup_location = array(
        'full_address'      => 'Woodlands, Singapore',
        'building_name'    => 0,
        'unit_number'       => 1,
        'contact_name' => 'John',
        'contact_phone'      => '1234567',
        'contact_company'      => 'CarPal',
        ‘lat’      => 12344,        
        ‘long’      => 122344,
        ‘customer_order_number’ => ‘123456’,
    );

delivery_locations

Each delivery location may have this field inside:

full_address
This is a mandatory field inside delivery location
This will indicate the location where the item is to be picked up.

cash_on_delivery_amount
This is an optional field inside delivery location
This will indicate the cash on delivery amount a driver must collect
It must be more than 0

item_quantity
This is an optional field inside delivery location
This will indicate item count.
It must be more than 1

grouping_location_id
This is an optional field inside delivery location

building_name
This is an optional field inside delivery location
This will indicate the building name where the item to be delivered

unit_number
This is an optional field inside delivery location
This will indicate the unit number where the item is to be delivered

contact_name
This is an optional field inside delivery location
This will be the delivery location contact name

contact_phone
This is an optional field inside delivery location
This will be the delivery location contact phone

contact_company
This is an optional field inside delivery location
This will be the delivery location contact company

lat
This is an optional field inside delivery location
This will be latitude of the delivery location

long
This is an optional field inside delivery location
This will be longitude of the delivery location

item
This is a mandatory field inside delivery location unless it was made optional through the Settings Module
This will be the description of the item to be delivered

customer_order_number
This is a mandatory field inside delivery location unless it was made optional through the Settings Module
sms_recipient_mobile_numbers
Comma-delimited list of recipients’ mobile numbers for SMS notifications. This field is optional.

waybill_number
This is an optional field inside delivery location
It must be a csv with each element of string with a maximum length of 25

      $delivery_locations = array(
      array(
        'full_address'      => 'Sentosa, Singapore',
        'building_name'    => 0,
        'unit_number'       => 1,
        'contact_name' => 'John',
        'contact_phone'      => '1234567',
        'contact_company'      => 'CarPal',
        'contact_email'      => ‘test@test.com’,
        'item' => 'Apples',
        ‘lat’      => 12344,        
        ‘long’      => 122344,
        ‘customer_order_number’ => ‘123456’,
        ‘grouping_location_id’ => '12345',
        ‘cash_on_delivery_amount’ => 10,
        ‘waybill_number’ => ABCXXX,
      ),
      array(
        'full_address'      => 'Woodlands, Singapore',
        'building_name'    => 0,
        'unit_number'       => 1,
        'contact_name' => 'Lee',
        'contact_phone'      => '1234567',
        'contact_company'      => 'CarPal',
        'contact_email'      => ‘test@test.com’,
        'item' => 'Apples',
        ‘lat’      => 12344,        
        ‘long’      => 122344,
        ‘customer_order_number’ => ‘123456’,
        ‘grouping_location_id’ => '12345',
        ‘item_quantity’ => 5,
      ),
      array(
        'full_address'      => 'Bukit Merah, Singapore',
        'building_name'    => 0,
        'unit_number'       => 1,
        'contact_name' => 'Kevin',
        'contact_email'      => ‘test@test.com’,
        'contact_phone'      => '1234567',
        'contact_company'      => 'CarPal',
        'item' => 'Apples',
        ‘lat’      => 12344,        
        ‘long’      => 122344,
        ‘customer_order_number’ => ‘123456’,
        ‘grouping_location_id’ => '12345',
      )
    );

 

optional fields

The following (optional) fields may be passed directly on your post request with ‘any’ value:

  • promo_code
  • delivery_notes

options

Note that the following opttions are always available even if you are using CarPal SaaS (although you can control the rate for it, but we will explain that later).

Note on format to trigger: i.e non_cbd_to_cbd = ‘on’

  • non_cbd_to_cbd
  • door_to_door_delivery
  • pet_service
  • pickup_timing_flexible
  • delivery_flexible (within 2 hours)
  • delivery_regular (within 6 hours) – default option
  • delivery_express (immediately after pickup)
  • secured_zone
  • return_trip
  • carrier_provided
  • extra_person
  • passenger
  • purchase_service
  • send_sms_notification
  • cash_on_delivery

Return Success:

  • Validation error (1)
  • Pricelist not set. Please contact Administrator (5)
  • Success (6)
  • Distance could not be calculated for Address* (*Address will resolve to the input address) (7)
  • Pickup time is less than 60 minutes from now. (*60 Minutes is the default time, this minute is dynamic based on settings) (8)
  • Pickup Location cannot be located (9)
  • Service select is invalid: Service Name* (*Service Name will resolve to the input service) (11)
  • Item is Mandatory for Each Delivery Location (20)
  • Sending of SMS Notification is disabled (24)
  • Invalid SMS Recipient Mobile Number (28)
  • Rate* has not been set (*Rate will resolve to the missing rate) (29)
  • Dropoff Address cannot be located (30)
  • The count of Waybill Numbers does not match the Item Quantity (32)
  • The Waybill Number must have max 25 Characters (33)

A successful quote will return you an ‘order_transient” that you will need to place the order.

Back To Top

Create order

You may create orders from an order_transient. If you have sub-customers (only applicable for CarPal Fleet customers) you can create orders for them (you should have passed the transaction_sub_customer_id when getting a quote).

POST url:

/v2/order

 

Fields:

  • order_transient (integer)
  • first_name (string)
  • last_name (string)
  • email (string)
  • phone (string)

Optional fields:

  • order_notes
  • company_name

Return Success:

  • Validation error (1)
  • Quote not found (2)
  • Not your quote (3)
  • This user is not a customer (4)
  • Country_code or currency not recognised (this can also mean that the quote is invalid) (5)
  • Something went wrong storing the order options (6)
  • Something went wrong while saving locations (7)
  • Succes (8)
  • Transaction Group does not exist (10)
  • Transaction Group does not belong to Customer (11)
  • Transaction Sub Customer Id is not related to your Account (12)

Return fields:

  • price
  • currency
  • order_id

Back To Top

Route Optimization

The CarPal system can create the optimal route for you between a fixed pick-up point, multiple waypoints and a fixed drop-off point. You can call this endpoint before passing the route to the Quote API and place the order.

The pickup point can be passed into the endpoint and the drop-off point is the destination (from the waypoint_locations array) that’s the furthest away from the pickup point.

The optimal route can be retrieved with your user account on POST url:

/v2/quote/get-best-direction

Fields:

  • ‘pickup_location’ => ‘required’
  • ‘waypoint_locations’ => ‘required|array’,
  • ‘identity_id’ => ‘required’,

Note: you may upload a maximum of 20 locations at the same time, additional charges apply for larger batches of locations.

Return Success:

  • Validation error (1)
  • Identity not found (2)
  • Pickup Location cannot be located (3)
  • Additional Stop Location cannot be located (4)
  • Directions cannot be routed (5)
  • Directions cannot be routed (6)
  • Address Information cannot be displayed for Place Id (7)
  • Success (8)

Back To Top

Cancel Order

You can cancel an order through the CarPal API until the moment it has been assigned with a driver. Credits will automatically be refunded to your account.

POST url:

/v2/order/cancel

Fields:

  • order_id

Return Success:

  • Validation error (1)
  • This user does not belong to a customer (2)
  • This order does not belong to this customer (3)
  • This order can not be cancelled (4)
  • Customer does not have a credit history (5)
  • No payment record was found (6)
  • Order cancelled (7)
  • An Order cannot be cancelled with a Driver (8)

Back To Top

Payment

To confirm and pay for the order you have to trigger the payment endpoint. The sandbox account has sufficient credits for testing.

If you trigger this endpoint as a sub-customer, you will be able to use the credits of the parent customer.

POST url:

/v2/payment/credits

Fields:

  • orderid

Return Success:

  • Validation error (1)
  • Order not found (2)
  • We could not find the correct price (3)
  • Not your order (4)
  • Payment not pending (5)
  • Success (6)
  • Payment failed (7)
  • Insufficient credits (8)
  • Customer has no credit history (9)
  • Grouping locations not found (10)
  • Parent Customer not set for Customer (11)
{
  "input_error": {
    "orderid": [
      "The orderid field is required."
    ]
  },
  "code": 1
}

Get Remaining Credits of Customer

POST url:

/v2/customer/credits

Return Success:

  • User is not a customer (1)
  • Success (2)

Back To Top

Order Status

Every order can have 7 different status.

The status can be retrieved through the following POST url:

 /v2/order/status/list
  • Pending: order has been placed but has not been paid for (1)
  • Dispatching: order has been paid for and the system is location a driver (2)
  • Confirmed: a driver has been confirmed (3)
  • Cancelled: the order has been cancelled (4)
  • Picked-up: the driver has picked-up the order (5)
  • Completed: the driver has completed the order (6)
  • Panic: the driver has hit the panic button and there is a problem with the order (7)
  • Paused: the driver has paused the order. (8)

Back To Top

Create Customers (CarPal Fleet)

You can create customers for your transaction groups. These customers will be able to login and place orders directly in your groups for the rates that you have set and use the credits of your balance.

Create Customer

POST url:

/v2/customer/transaction/create-sub-customer

Fields:

  • identity_id (required)
  • product_type_id (required|int)
  • transaction_group_id (required|array)
  • first_name (required)
  • last_name (required)
  • email (required|email)
  • password (required)
  • birthday (date_format:Y-m-d)
  • phone (numeric)

Return Success:

  • Validation Error (1)
  • User could not be found (2)
  • User is not a customer (3)
  • Invalid Product Type Id passed (4)
  • Invalid Transaction Id passed (5)
  • Authenticated User does not belong to Transaction Group passed (6)
  • Existing User Email does not match a User (7)
  • Existing User is already a customer (8)
  • User Fields Validation Error (9)
  • Success (10)

 

List Customers

POST url:

/v2/customer/transaction/subcustomers

Fields:

  • identity_id (required)
  • product_type_id (array|required)
  • transaction_group_id (array|required)

Return Success:

  • Validation Error (1)
  • Identity does not exists (2)
  • Product Type contain invalid ids (3)
  • Product Type Passed does not belong to Customer (4)
  • Transaction Group contain invalid ids (5)
  • Transaction Group Passed does not belong to Customer (6)
  • Success (7)

Back To Top

Transaction Groups (CarPal Fleet)

CarPal Fleet customers can create private ‘Transaction Groups’ to assign drivers and orders.

Create Transaction Group

POST url:

/v2/customer/transaction/create-transaction-group

Fields:

  • ‘name’ => ‘required|numeric’

Return Success:

  • Validation error (1)
  • User could not be found (2)
  • User is not a customer (3)
  • Transaction Group with specified name exists already (4)
  • Success (5)

Edit Transaction Group

POST url:

/v2/customer/transaction/edit-transaction-group

Fields:

  • ‘name’ => ‘required’
  • ‘transaction_group_id’ => ‘required|int’,

Return Success:

  • Validation error (1)
  • User could not be found (2)
  • User is not a customer (3)
  • Transaction Group with specified name exists already (4)
  • Transaction Group does not exist (5)
  • Success (6)
  • You are not part of this Transaction Group (7)

Get all Customer Transaction Groups

POST url:

/v2/customer/transaction/customer-transaction-groups

Fields:

  • ‘identity_id’ => ‘required|numeric’
  • ‘customer_id’ => ‘required|numeric’

Return Success:

  • Validation error (1)
  • User could not be found (2)
  • User is not a customer (3)
  • Customer does not exist (4)
  • Identity does not exist(5)
  • Customer does not belong to Identity passed
    (6)
  • Success (7)

Back To Top

Edit Order (CarPal Fleet)

As a CarPal Fleet customer you can edit your order (or the orders of your customers). A sub customer can only change the order before a driver has been assigned.

POST url:

/v2/customer/transaction/order/update

 

Fields:

  • identity_id (integer|required)
  • order_id (integer|required)
  • pickup_date (date|date_format:Y-m-d)
  • pickup_timing (date_format:H:i)
  • order_notes (optional)
  • first_name (optional)
  • last_name (optional)
  • phone (optional)
  • driver_fee (optional)

Return Success:

  • Validation error (1)
  • User could not be found (2)
  • User is not a customer (3)
  • Identity does not exist< (4)
  • Order not found (5)
  • Order Detail not found (6)
  • This order does not belong to this customer (8)
  • Success (7)
  • Order Status passed does not exist (9)
  • ‘OrderStatus error’ (10)
  • Order Update Setttings is not set (11)
  • Pickup Date is not changeable by customer (12)
  • Pickup Time is not changeable by customer (13)
  • Delivery Notes is not changeable by customer (14)
  • Driver Fee is not changeable by customer (15)
  • Phone is not changeable by customer (16)
  • Order Notes is not changeable by customer (17)
  • Order Status Id is not changeable by customer (18)
  • First Name is not changeable by customer (19)
  • Last Name is not changeable by customer (20)
  • Order has a Driver and is not changeable (21)

Back To Top

Drivers (CarPal Fleet)

A CarPal Fleet customer can create drivers. These drivers are initially set to a private group and hence one or multiple transaction_group_id’s (that was created prior to creating the driver) have to be passed to this endpoint.

Create drivers

POST url:

/v2/customer/transaction/create-driver

Fields:

  • ‘identity_id’ => ‘required|numeric’
  • ‘product_type_id’ => ‘required|numeric’,
  • ‘transaction_group_id’ => ‘required|array’,
  • ‘first_name’ => ‘required’,
  • ‘last_name’ => ‘required’,
  • ‘email’ => ‘required|email’,
  • ‘password’ => ‘required’,
  • ‘birthday’ => ‘(date_format:Y-m-d)’,
  • ‘phone’ => ‘numeric’,
  • ‘send_confirmation_sms’ (boolean – optional – additional costs apply)

Return Success:

  • Validation error (1)
  • User could not be found (2)
  • User is not a customer (3)
  • Invalid Product Type Id passed (4)
  • Invalid Transaction Id passed (5)
  • Authenticated User does not belong to Transaction Group passed (6)
  • Existing User Email does not match a User (7)
  • Existing User is already a driver (8)
  • User Fields Validation Error (9)
  • Success (10)
  • Sending of SMS Notification is disabled (11)

Edit Driver

Get all Drivers

POST url:

/v2/customer/transaction/drivers

Fields:

  • ‘identity_id’ => ‘required|numeric’
  • ‘product_type_id’ => ‘required|array’,
  • ‘transaction_group_id’ => ‘optional|array’,
  • ‘driver_status_ids’ => ‘optional|array’,
  • ‘show_drivers_with_orders’ => ‘optional|boolean’,

If show_drivers_with_orders is set to true, check ‘assigned_order_id’ in the response for the order(s) assigned to driver.

Return Success:

  • Validation error (1)
  • User could not be found (2)
  • User is not a customer (3)
  • No drivers found (4)
  • Product Type contain invalid ids (5)
  • Transaction Group contain invalid ids
    (6)
  • Success (7)
  • Product Type passed does not belong to Customer (8)
  • Transaction Group passed does not belong to Customer (9)
  • Driver Status contain invalid ids (10)

Assign drivers to order

POST url:

/v2/customer/transaction/order-set-driver

Fields:

  • ‘driver_id’ => ‘required|numeric’
  • ‘order_id’ => ‘required|numeric’,

Return Success:

  • Validation error (1)
  • Order not found (2)
  • A Driver has already been matched (3)
  • Driver not found (4)
  • Success (5)
  • Order belongs to another Customer (6)

Remove driver from order

POST url:

/v2/customer/transaction/order-reset-driver

Fields:

  • Validation error (1)
  • Order does not exist (2)
  • Order belongs to another customer (3)
  • Success (4)

Back To Top

Retrieve Orders

Allows you to get all the Orders with additional informations such as Details, Addresses and Routes. Specific orders desired can also be pulled by passing the order ids. You can also retrieve the orders of your customers.

POST url:

/v2/customer/orders/

Optional field:

  • order_ids (array)
  • show_transaction_sub_customers_orders (bool)
  • order_status_ids (array | optional)
  • pickup_date_start (date | date_format:Y-m-d | before:pickup_date_end | optional)
  • pickup_date_end (date | date_format:Y-m-d | after:pickup_date_start | optional)

Result success:

  • User could not be found (1)
  • User is not a customer (2)
  • No orders found (3)
  • Success (4)
  • Validation Error (5)
  • Customer does not have Transaction Sub Customers (6)
  • Order Status contain invalid ids (7)

Get Order images

POST url:

/v2/customer/orders/images

Required fields:

  • identity_id
  • order_id

Result success:

  • Validation Error (1)
  • User could not be found (2)
  • User is not a customer (3)
  • Identity could not be found (4)
  • Order can not be found (5)
  • Order is not in the Identity passed (6)
  • Failed getting image externally (7)
  • Success (8)
  • Order belongs to another customer (9)

Back To Top

Location Grouping

This endpoint provides a ‘grouping’ service for bulk deliveries.

This endpoint returns a grouping_batch_number that can be used to call the Get Grouping results endpoint and retrieve the grouped results.

Set Location Grouping

POST url: /v2/grouping/set-location-grouping

Fields:

  • pickup_location (required)
  • pickup_date (required|date_format:Y-m-d)
  • pickup_time (required|date_format:H:i)
  • max_locations_per_group (required)
  • max_meters_distance (required)
  • is_grouped_by_distance_limit (required)
  • product_service_id (required)
  • order_option_id (required)
  • transaction_group_id
  • delivery_locations (required|json)
  • additional_order_options_id (optional|array)

The delivery locations must be a json encoded array containing:

  • address (required)
  • location_data (optional)

Result codes:

  • User is not a Customer (1)
  • Validation Error (2)
  • Product Service can not be found (3)
  • Order Option can not be found (4)
  • Pickup Location can not be detected (5)
  • Invalid Delivery Locations Format (6)
  • Delivery Locations Validation Error (7)
  • Success (8)
  • Grouping Locations Per Batch is limited to MAXIMUM GROUPING LOCATIONS (9)
  • Transaction Group can not be found (10)
  • Transaction Group does not belong to Customer (11)
  • Additional Order Options contain invalid IDs (12)

 

Show Grouping Batch

POST url: /v2/grouping/show-grouping-batch
header: ‘Authorization’ : Bearer JSON token

Fields:

  • grouping_batch_id (required)

Result codes:

  • User is not a customer (1)
  • Validation error (2)
  • Grouping Batch not found (3)
  • Success (4)

Back To Top

Product Services (CarPal Fleet)

Get Product Services

POST url:

/v2/product-service

Fields:

  • identity_id (required)
  • product_type_id (required)
  • transaction_group_id

 

 

 

Back To Top