NAV Navbar
Logo
shell php javascript

Introduction

Using the Alopeyk API, businesses can easily integrate our on-demand delivery service into their platform whether they use an E-Commerce platform (Magento, Prestashop, OpenCart, WooCommerce, etc.) or they have developed their own app.

This API is designed to allow developers to check out our pricings, create orders, and track updates on that order until completion.

Environments

There are two available environments: Sandbox and Production, both share the same codebase.

Sandbox environment is for testing your app compatibility with Alopeyk’s API.

Production environment is a real-time and after testing your app with Sandbox you can ask for production token To get started using the Alopeyk Delivery API you need to submit a request for a sandbox access token.

Sandbox

https://sandbox-api.alopeyk.com/api/v2/

Sandbox environment allows you to test your integration without sending requests to real drivers. It also comes with a simulator that allows your requests to be handled by bots acting like real drivers (they accept orders, ‘drive’ from origin to destination and so on). You can run your implementations on the staging area just as you would on “production-like” conditions.

In this environment, the order status changes every 30 seconds and it stops changing as soon as get to delivered. For more details, please check Tracking documentation.

Production

https://api.alopeyk.com/api/v2/

If you feel ready to move your code to production and start using the Alopeyk’s API with real drivers, please fill out this form. We will contact you to check your app and generate your Production Token.

Client libraries

To have complete access to Alopeyk’s all API libraries you need check this Github Repositories. Some of the most useful repositories are listed below.

PHP

You can access and contribute to the official PHP Library available on github. For more details about how to use it, you need read the README.md file.

Laravel

You can access and contribute to the official Laravel Library available on github and also on Packagist. For more details about how to use it, you need read the README.md file.

Woocommerce

If your online shop has based on Woocommerce, you can use the official Alopeyk’s Woocommerce Plugin available on github and aslo on Wordpress plugin directory. For more details about how to use it, you need read the Installation Guide.

Basics

The Alopeyk API is fully RESTful:

API Rate Limits

Our API is limited Per IP. Rate limiting of the API is primarily structured on a per-user basis, but all requests made before being authenticated are rate limited by the IP source of that request.

Our main limit factors are Request Per Minute and Request Per Day. If you pass any of these two rate limitations, your access will be limited or blocked for a specified time window, so you’ll have to wait until that duration is over.

Minute Rate Limit

Currently you can send up to 100 requests every minute. You will be able to check the current quotas on every response header.

Response Header

{
...
"X-MinuteRateLimit-Identifier": "[IP]:[YYYY]-[MM]-[DD]-[hh]-[mm]",
"X-MinuteRateLimit-Limit": "100",
"X-MinuteRateLimit-Remaining": "XX"
...
}

Daily Rate Limit

Currently you can send up to 43200 requests every day. You will be able to check the current quotas on every response header.

Response Header

{
...
"X-DailyRateLimit-Identifier": "[IP]:[YYYY]-[MM]-[DD]-[hh]-[mm]",
"X-DailyRateLimit-Limit": "43200",
"X-DailyRateLimit-Remaining": "XX"
...
}

Authentication
GET

For Authentication, use this code:

curl "https://sandbox-api.alopeyk.com/api/v2/" \
  -X GET \
  -H "Authorization: Bearer ${$token}" \
  -H "X-Requested-With: XMLHttpRequest"
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://sandbox-api.alopeyk.com/api/v2/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING       => "",
  CURLOPT_MAXREDIRS      => 10,
  CURLOPT_TIMEOUT        => 30,
  CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST  => "GET",
  CURLOPT_HTTPHEADER     => [
    "Authorization: Bearer " . $token,
    "X-Requested-With: XMLHttpRequest"
  ],
]);

$response = curl_exec($curl);
$err      = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}

?>
var data = null;

var xhr = new XMLHttpRequest();

xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open('GET', 'https://sandbox-api.alopeyk.com/api/v2/');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.send(data);

Make sure to replace $token with your own JWT Token.

All Alopeyk API endpoints support the JWT authentication protocol.

To start sending authenticated HTTP requests you will need to use your JWT authorization token which is sent to you.

Since you have a valid token you need to add it as an HTTP header to every HTTP request you send to the Alopeyk API.

GET https://sandbox-api.alopeyk.com/some_endpoint HTTP/1.1
Authorization: Bearer <JWT_TOKEN>
Host: sandbox-api.alopeyk.com

Your JWT token will have a long expiration time, although that duration could be decreased in the future. Note that your token will not be expired until you request a new one.

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.......................

Location

GET
Get Address

curl "https://sandbox-api.alopeyk.com/api/v2/locations?latlng=35.755484%2C51.415306" \
  -X GET \
  -H "Authorization: Bearer {$token}" \
  -H "X-Requested-With: XMLHttpRequest"
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox-api.alopeyk.com/api/v2/locations?latlng=35.756780%2C51.411255",



  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING       => "",
  CURLOPT_MAXREDIRS      => 10,
  CURLOPT_TIMEOUT        => 30,
  CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST  => "GET",
  CURLOPT_HTTPHEADER     => [
    "Authorization: Bearer " . $token,
    "X-Requested-With: XMLHttpRequest"
  ],
]);

$response = curl_exec($curl);
$err      = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}
var data = null;

var xhr = new XMLHttpRequest();

xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open('GET', 'https://sandbox-api.alopeyk.com/api/v2/locations?latlng=35.756780%2C51.411255');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.send(data);

The above command returns a JSON response structured like this:

{
  "status": "success",
  "message": "findPlace",
  "object": {
    "address": [
      "بیستم",
      "گاندی جنوبی"
    ],
    "region": "ونک",
    "district": "",
    "city": "tehran",
    "traffic_zone": {
      "congestion": false,
      "odd_even": false
    },
    "city_fa": "تهران",
    "province": "تهران"
  }
}

This endpoint retrieves place information by its latitude and longitude.

HTTP Request

GET https://sandbox-api.alopeyk.com/api/v2/locations

Query Parameters

Parameter Default Required Description
latlng NULL true Fill this parameter with your place latitude and longitude

GET
Location Suggestions

curl 'https://sandbox-api.alopeyk.com/api/v2/locations?input=میرداماد' \
  -X GET \
  -H 'Authorization: Bearer {$token}' \
  -H 'X-Requested-With: XMLHttpRequest'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://sandbox-api.alopeyk.com/api/v2/locations?input=میرداماد",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING       => "",
  CURLOPT_MAXREDIRS      => 10,
  CURLOPT_TIMEOUT        => 30,
  CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST  => "GET",
  CURLOPT_HTTPHEADER     => [
    "Authorization: Bearer " . $token,
    "X-Requested-With: XMLHttpRequest"
  ],
]);

$response = curl_exec($curl);
$err      = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}
var data = null;

var xhr = new XMLHttpRequest();

xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open('GET', 'https://sandbox-api.alopeyk.com/api/v2/locations?input=میرداماد');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.send(data);

The above command returns a JSON response structured like this:

{
  "status": "success",
  "message": "autoComplete",
  "object": [
    {
      "title": "میرداماد",
      "region": "شیوا",
      "lat": "35.680097111817098",
      "lng": "51.466359241720198",
      "district": "منطقه ۱۴",
      "city": "tehran",
      "city_fa": "تهران"
    },
    {
      "title": "میرداماد",
      "region": "مینایی",
      "lat": "35.654716852415099",
      "lng": "51.4560997326357",
      "district": "منطقه ۱۵",
      "city": "tehran",
      "city_fa": "تهران"
    },
    {
      "title": "میرداماد",
      "region": "داودیه",
      "lat": "35.760104930870803",
      "lng": "51.432777284209102",
      "district": false,
      "city": "tehran",
      "city_fa": "تهران"
    },
    {
      "title": "میرداماد",
      "region": "tehran",
      "lat": "35.5386945664753",
      "lng": "51.2160959801693",
      "district": false,
      "city": "tehran",
      "city_fa": "تهران"
    },
    {
      "title": "بلوار میرداماد",
      "region": "داودیه",
      "lat": "35.7600557285908",
      "lng": "51.431922949816098",
      "district": false,
      "city": "tehran",
      "city_fa": "تهران"
    }
  ]
}

This endpoint retrieves suggestions by search input.

The result will be an array of suggestions. Each one includes the region and the name of the retrieved place, and offers coordinates for that item.

HTTP Request

GET https://sandbox-api.alopeyk.com/api/v2/locations

Query Parameters

Parameter Default Required Description
input NULL true Fill this parameter with your search input

Price

POST
Normal Price

Request a quote for an order with origin address and destination address

curl 'https://sandbox-api.alopeyk.com/api/v2/orders/price/calc' \
  -X POST \
  -H 'Authorization: Bearer {$token}' \
  -H 'X-Requested-With: XMLHttpRequest' \
  -H 'Content-Type: application/json; charset=utf-8' \
  --DATA '{"transport_type":"motor_taxi","addresses":[{"type":"origin","lat":"35.755460","lng":"51.416874"},{"type":"destination","lat":"35.758495","lng":"51.442550"},{"type":"destination","lat":"35.895452","lng":"51.589632"}],"has_return":false,"cashed":false}'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://sandbox-api.alopeyk.com/api/v2/orders/price/calc",
  CURLOPT_RETURNTRANSFER => **true**,
  CURLOPT_ENCODING       => "",
  CURLOPT_MAXREDIRS      => 10,
  CURLOPT_TIMEOUT        => 30,
  CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST  => "POST",
  CURLOPT_POSTFIELDS     => json_encode(
    [
      "transport_type" => "motor_taxi",
      "addresses"      => [
        [
          "type" => "origin",
          "lat"  => 35.756780,
          "lng"  => 51.411255,
        ],
        [
          "type" => "destination",
          "lat"  => 35.758495,
          "lng"  => 51.442550,
        ],
        [
          "type" => "destination",
          "lat"  => 35.895452,
          "lng"  => 51.589632,
        ],
      ],
      "has_return" => *false*,
      "cashed"     => *false*,
    ]
  ),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . $token,
    "Content-Type: application/json; charset=utf-8",
    "X-Requested-With: XMLHttpRequest"
  ],
]);

$response = curl_exec($curl);
$err      = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}
var data = JSON.stringify({
  'transport_type': 'motor_taxi',
  'addresses': [
    {
      'type': 'origin',
      'lat' : 35.756780,
      'lng' : 51.411255,
    },
    {
      'type': 'destination',
      'lat' : 35.758495,
      'lng' : 51.442550,
    },
    {
      'type': 'destination',
      'lat' : 35.895452,
      'lng' : 51.589632,
    },
  ],
  'has_return': false,
  'cashed': false
});

var xhr = new XMLHttpRequest();

xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open('POST', 'https://sandbox-api.alopeyk.com/api/v2/orders/price/calc');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader("Content-Type", "application/json; charset=utf-8");

xhr.send(data);

The above command returns JSON structured like this:

{
  "status": "success",
  "message": null,
  "object": {
    "addresses": [
      {
        "type": "origin",
        "lat": 35.75678,
        "lng": 51.411255,
        "address": "تهران، منطقه ۳، کاووسیه، خ گاندی، خ بیستم",
        "city": "tehran",
        "city_fa": "تهران",
        "priority": 0
      },
      {
        "type": "destination",
        "lat": 35.758495,
        "lng": 51.44255,
        "address": "منطقه ۳، داودیه، میرداماد جنوبی، م مادر ابتدای خ بهروز",
        "city": "tehran",
        "city_fa": "تهران",
        "priority": 1,
        "distance": 2830,
        "duration": 349,
        "coefficient": 1,
        "price": 8000
      },
      {
        "type": "destination",
        "lat": 35.895452,
        "lng": 51.589632,
        "address": "بخش رودبارقصران، روستای امامه پایین",
        "city": "tehran",
        "city_fa": "تهران",
        "priority": 2,
        "distance": 20192,
        "duration": 2492,
        "coefficient": 0.42308,
        "price": 25500
      }
    ],
    "price": 33500,
    "credit": true,
    "distance": 23022,
    "duration": 2841,
    "status": "OK",
    "user_credit": 1685000,
    "delay": 0,
    "city": "tehran",
    "city_fa": "تهران",
    "transport_type": "motor_taxi",
    "has_return": false,
    "cashed": false,
    "price_with_return": 46500,
    "score": 670,
    "score_detail": {
      "انجام درخواست": 335,
      "اعتباری": 335
    },
    "final_price": 33500,
    "discount": 0,
    "discount_coupons": [],
    "invalid_discount_coupons": [],
    "failed_final_price": 0,
    "failed_discount": 0,
    "failed_discount_coupons": [],
    "scheduled": false
  }
}

This endpoint retrieves calculation information for a pair of {latitude,longitude}s.

HTTP Request

POST https://sandbox-api.alopeyk.com/api/v2/orders/price/calc

Request Parameters

Parameter Default Required Description
transport_type NULL true The transport type of the order. Currently valid values for this attribute are motorbike for simple package delivery, motor_taxi for passenger transportations, cargo for cargo, cargo_s for Small Cargo, and car for Car transportations.
addresses[0][type] NULL true Must be of type origin.
addresses[0][lat] NULL true Latitude of the origin address.
addresses[0][lng] NULL true Longitude of the origin address.
addresses[1][type] NULL true Must be of type destination.
addresses[1][lat] NULL true Latitude of the first destination address.
addresses[1][lng] NULL true Longitude of the first destination address.
addresses[2][type] NULL false Must be of type destination.
addresses[2][lat] NULL false Latitude of extra destination addresses.
addresses[2][lng] NULL false Longitude of extra destination addresses.
has_return false false If you are going to calculate price for an order which has a return option, set it to true.
cashed false false If you are going to force the payment type as cash, set it to true.

Response Descriptions

Attribute Description
status Indicates that the calculation progress has been successful or not.
price Total calculated price.
credit Indicates payment type of the order (payment by credit or cash). Will be true only if you have enough credit on your account for that order. In the case of credit deficiency, or cashed=true, this attribute will be set to false.
distance Estimated distance between the source and the destination (Provided by Google ETA).
duration Estimated duration of the path between the source and the destination (Based on Google Distance Matrix ETA).
user_credit Your current credit (in Tomans).
price_with_return Calculated price for the order, in case of has_return=true.

POST
Batch Price

This endpoint is the same as Normal Price But the difference is you can calculate up to 15 pairs of Normal Price in one request.

curl 'https://sandbox-api.alopeyk.com/api/v2/orders/batch-price' \
  -X POST \
  -H 'Authorization: Bearer {$token}' \
  -H 'X-Requested-With: XMLHttpRequest' \
  -H 'Content-Type: application/json; charset=utf-8' \
  --DATA '[{"transport_type":"car","addresses":[{"type":"origin","lat":35.75678,"lng":51.411255},{"type":"destination","lat":35.758495,"lng":51.44255},"has_return":false,"cashed":false},{"transport_type":"motor_taxi","addresses":[{"type":"origin","lat":35.75678,"lng":51.411255},{"type":"destination","lat":35.895452,"lng":51.589632}],"has_return":false,"cashed":false}]'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://sandbox-api.alopeyk.com/api/v2/orders/batch-price",
  CURLOPT_RETURNTRANSFER => **true**,
  CURLOPT_ENCODING       => "",
  CURLOPT_MAXREDIRS      => 10,
  CURLOPT_TIMEOUT        => 30,
  CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST  => "POST",
  CURLOPT_POSTFIELDS     => json_encode(
    [
      [
        "transport_type" => "car",
        "addresses"      => [
          [
            "type" => "origin",
            "lat"  => 35.756780,
            "lng"  => 51.411255,
          ],
          [
            "type" => "destination",
            "lat"  => 35.758495,
            "lng"  => 51.442550,
          ],
        ],
        "has_return" => false,
        "cashed"     => false,
      ],
      [
        "transport_type" => "motor_taxi",
        "addresses"      => [
          [
            "type" => "origin",
            "lat"  => 35.756780,
            "lng"  => 51.411255,
          ],
          [
            "type" => "destination",
            "lat"  => 35.895452,
            "lng"  => 51.589632,
          ],
        ],
        "has_return" => false,
        "cashed"     => false,
      ]
    ]
  ),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . $token,
    "Content-Type: application/json; charset=utf-8",
    "X-Requested-With: XMLHttpRequest"
  ],
]);

$response = curl_exec($curl);
$err      = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}
var data = JSON.stringify([
  {
    "transport_type": "car",
    "addresses": [
      {
        "type": "origin",
        "lat": 35.75678,
        "lng": 51.411255
      },
      {
        "type": "destination",
        "lat": 35.758495,
        "lng": 51.44255
      }
    ],
    "has_return": false,
    "cashed": false
  },
  {
    "transport_type": "motor_taxi",
    "addresses": [
      {
        "type": "origin",
        "lat": 35.75678,
        "lng": 51.411255
      },
      {
        "type": "destination",
        "lat": 35.895452,
        "lng": 51.589632
      }
    ],
    "has_return": false,
    "cashed": false
  }
]);

var xhr = new XMLHttpRequest();

xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open('POST', 'https://sandbox-api.alopeyk.com/api/v2/orders/batch-price');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader("Content-Type", "application/json; charset=utf-8");

xhr.send(data);

The above command returns JSON structured like this:

{
  "status": "success",
  "message": null,
  "object": [
    {
      "addresses": [
        {
          "type": "origin",
          "lat": 35.75678,
          "lng": 51.411255,
          "address": "تهران، منطقه ۳، کاووسیه، خ گاندی، خ بیستم",
          "city": "tehran",
          "city_fa": "تهران",
          "priority": 0
        },
        {
          "type": "destination",
          "lat": 35.758495,
          "lng": 51.44255,
          "address": "منطقه ۳، داودیه،  میرداماد جنوبی، م مادر ابتدای خ بهروز",
          "city": "tehran",
          "city_fa": "تهران",
          "priority": 1,
          "distance": 2830,
          "duration": 174,
          "coefficient": 0.9068,
          "price": 6000
        }
      ],
      "price": 6000,
      "credit": true,
      "distance": 2830,
      "duration": 174,
      "status": "OK",
      "user_credit": 1000,
      "delay": 0,
      "city": "tehran",
      "city_fa": "تهران",
      "transport_type": "car",
      "has_return": false,
      "cashed": false,
      "price_with_return": 9000,
      "score": 120,
      "score_detail": {
        "انجام درخواست": 60,
        "اعتباری": 60
      },
      "final_price": 6000,
      "discount": 0,
      "discount_coupons": [],
      "invalid_discount_coupons": [],
      "failed_final_price": 0,
      "failed_discount": 0,
      "failed_discount_coupons": [],
      "scheduled": false
    },
    {
      "addresses": [
        {
          "type": "origin",
          "lat": 35.75678,
          "lng": 51.411255,
          "address": "تهران، منطقه ۳، کاووسیه، خ گاندی، خ بیستم",
          "city": "tehran",
          "city_fa": "تهران",
          "priority": 0
        },
        {
          "type": "destination",
          "lat": 35.895452,
          "lng": 51.589632,
          "address": "بخش رودبارقصران، روستای امامه پایین",
          "city": "tehran",
          "city_fa": "تهران",
          "priority": 1,
          "distance": 22279,
          "duration": 2749,
          "coefficient": 0.4,
          "price": 26500
        }
      ],
      "price": 26500,
      "credit": true,
      "distance": 22279,
      "duration": 2749,
      "status": "OK",
      "user_credit": 1000,
      "delay": 0,
      "city": "tehran",
      "city_fa": "تهران",
      "transport_type": "motor_taxi",
      "has_return": false,
      "cashed": false,
      "price_with_return": 39500,
      "score": 530,
      "score_detail": {
        "انجام درخواست": 265,
        "اعتباری": 265
      },
      "final_price": 26500,
      "discount": 0,
      "discount_coupons": [],
      "invalid_discount_coupons": [],
      "failed_final_price": 0,
      "failed_discount": 0,
      "failed_discount_coupons": [],
      "scheduled": false
    }
  ]
}

HTTP Request

POST https://sandbox-api.alopeyk.com/api/v2/orders/batch-price

Request Parameters

Parameter Default Required Description
transport_type NULL true The transport type of the order. Currently valid values for this attribute are motorbike for simple package delivery, motor_taxi for passenger transportations, cargo for cargo, cargo_s for Small Cargo, and car for Car transportations.
addresses[0][type] NULL true Must be of type origin.
addresses[0][lat] NULL true Latitude of the origin address.
addresses[0][lng] NULL true Longitude of the origin address.
addresses[1][type] NULL true Must be of type destination.
addresses[1][lat] NULL true Latitude of the first destination address.
addresses[1][lng] NULL true Longitude of the first destination address.
has_return false false If you are going to calculate price for an order which has a return option, set it to true.
cashed false false If you are going to force the payment type as cash, set it to true.

Response Descriptions

Attribute Description
status Indicates that the calculation progress has been successful or not.
price Total calculated price.
credit Indicates payment type of the order (payment by credit or cash). Will be true only if you have enough credit on your account for that order. In the case of credit deficiency, or cashed=true, this attribute will be set to false.
distance Estimated distance between the source and the destination (Provided by Google ETA).
duration Estimated duration of the path between the source and the destination (Based on Google Distance Matrix ETA).
user_credit Your current credit (in Tomans).
price_with_return Calculated price for the order, in case of has_return=true.

Orders

Order Handling Details

Below you can find different steps for order completion:

1- Creating an order: In the beginning, the order has a status of new, which tells us that the order has been newly created. The order has to have at least two addresses. The first address is always of the type origin, and the second one is of the type destination. if the order contains a has return option, the last address of the order will be of type return, but it will be no different than origin or destination addresses. Orders can have multiple destination addresses. Destination addresses are currently limited to 5. In this stage every address will be in a pending status. At this point the order can be cancelled by you, see the next step for more details on canceling an order.

2- Now it’s time to start dispatching the order. In this step, the order will attain a searching status. This means that we will be searching amongst our available couriers who are closest to the origin address listed inside the addresses list. The timestamp on which the dispatching process is started will be set as the launched_at attribute on the order object. If no couriers are found for the order, or no courier accepts the order, the dispatcher machine will stop searching after 10 minutes, and update the order status to expired. You will be able to cancel the order up until this point. After canceling, the status will change to cancelled, and the cancelled_by attribute, which contains your id, will be set. In both expiration and cancellation cases, the stopped_at attribute will tell us exactly when the progress has been stopped.

3- Accepting an order: When an order is accepted by one of our couriers, the status of the order will be changed to accepted and the accepted_at attribute will be filled by the timestamp of the acceptance time. The distance and duration attributes of the first address (the origin address), will be set by the distance and duration calculated based the position of the courier at which he has accepted the order. You can also cancel the order after this step. From now on, all other actions will affect addresses. Actions on first address of the order (The origin address), will also affect the order, changing the status, picking_at and delivering_at values. Other addresses, except the last one, will not affect the order. The last address fills the delivered_at and status attributes to the time when the order is delivered and the devlivered status respectively.

4- Arriving to the origin: In this step the status of the origin address will be changed to arrived and the arrived_at attribute will be filled by the time of courier arrival. Also the status of the order will be changed to picking, and the picking_at attribute will be filled by arrived_at‘s value. In this step, the courier can reject the order after 5 minutes if he is not able to see any progress, or has mutually agreed with you to cancel the order. In this case, the status of the order will be changed to cancelled, and the cancelled_by attribute will be changed to the id of the responsible courier, also stopped_at will be filled by the time of the cancellation.

5- Handling the origin address: The status of the origin address will be changed to handled and the handled_at attribute will be filled by the time the address is handled, also the status of the order will be changed to delivering, and the delivering_at attribute will be filled by handled_at’s value.

6- Arriving to next address: The status of the next address which is usually a destination address, but can also be a return address if the courier needs to return to the first address, will also be changed to arrived and the arrived_at attribute will be filled by the time of arrival. Not that the order’s information will not be touched during this step.

7- Handling the next address: The status of the next address which again is usually a destination address, but can also be a return address if the courier needs to return to the first address, will be changed to handled and the handled_at attribute will be filled by the time of handling the address. If this is the last address, the address type will be return in case the order has a return option. Otherwise, this address will also be of type destination. Now the status of the order will be changed to delivered, and the delivered_at attribute will be filled by the handled_at value.

8- Finishing the order. The status of the order will be changed to finished and the finished_at attribute will be filled by timestamp the order has been finished.

POST
Create Order

curl 'https://sandbox-api.alopeyk.com/api/v2/orders' \
  -X POST \
  -H 'Authorization: Bearer {$token}' \
  -H 'X-Requested-With: XMLHttpRequest' \
  -H 'Content-Type: application/json; charset=utf-8' \
  --DATA '{"transport_type":"motor_taxi","addresses":[{"type":"origin","lat":"35.755460","lng":"51.416874","description":"some description for origin","unit":"unit of origin address","number":"number of origin address","person_fullname":"sender s name","person_phone":"sender s phone"},{"type":"destination","lat":"35.758495","lng":"51.442550","description":"some description for origin","unit":"unit of origin address","number":"number of origin address","person_fullname":"sender s name","person_phone":"sender s phone"},{"type":"destination","lat":"35.895452","lng":"51.589632","description":"some description for origin","unit":"unit of origin address","number":"number of origin address","person_fullname":"sender s name","person_phone":"sender s phone"}],"has_return":false,"cashed":false}'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://sandbox-api.alopeyk.com/api/v2/orders",
  CURLOPT_RETURNTRANSFER => **true**,
  CURLOPT_ENCODING       => "",
  CURLOPT_MAXREDIRS      => 10,
  CURLOPT_TIMEOUT        => 30,
  CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST  => "POST",
  CURLOPT_POSTFIELDS     => json_encode(
    [
      "transport_type" => "motor_taxi",
      "addresses"      => [
        [
          "type"            => "origin",
          "lat"             => 35.756780,
          "lng"             => 51.411255,
          "description"     => "some description for origin",
          "unit"            => "unit of origin address",
          "number"          => "number of origin address",
          "person_fullname" => "sender s name",
          "person_phone"    => "sender s phone",
        ],
        [
          "type"            => "destination",
          "lat"             => 35.758495,
          "lng"             => 51.442550,
          "description"     => "some description for destination",
          "unit"            => "unit of destination address",
          "number"          => "number of destination address",
          "person_fullname" => "receiver s name",
          "person_phone"    => "receiver s phone",
        ],
        [
          "type"            => "destination",
          "lat"             => 35.895452,
          "lng"             => 51.589632,
          "description"     => "some description for destination",
          "unit"            => "unit of destination address",
          "number"          => "number of destination address",
          "person_fullname" => "receiver s name",
          "person_phone"    => "receiver s phone"
        ]
      ],
      "has_return" => false,
      "cashed"     => false
    ]
  ),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . $token,
    "Content-Type: application/json; charset=utf-8",
    "X-Requested-With: XMLHttpRequest"
  ],
]);

$response = curl_exec($curl);
$err      = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}
var data = JSON.stringify({
  "transport_type": "motor_taxi",
  "addresses": [
    {
      "type": "origin",
      "lat": "35.756780",
      "lng": "51.411255",
      "description": "some description for origin",
      "unit": "unit of origin address",
      "number": "number of origin address",
      "person_fullname": "sender s name",
      "person_phone": "sender s phone"
    },
    {
      "type": "destination",
      "lat": "35.758495",
      "lng": "51.442550",
      "description": "some description for destination",
      "unit": "unit of destination address",
      "number": "number of destination address",
      "person_fullname": "receiver s name",
      "person_phone": "receiver s phone"
    },
    {
      "type": "destination",
      "lat": "35.895452",
      "lng": "51.589632",
      "description": "some description for destination",
      "unit": "unit of destination address",
      "number": "number of destination address",
      "person_fullname": "receiver s name",
      "person_phone": "receiver s phone"
    }
  ],
  "has_return": false,
  "cashed": false
});

var xhr = new XMLHttpRequest();

xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open('POST', 'https://sandbox-api.alopeyk.com/api/v2/orders');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader('Content-Type', 'application/json; charset=utf-8');

xhr.send(data);

The above command returns a JSON response structured like this:

{
  "status": "success",
  "message": null,
  "object": {
    "transport_type": "motor_taxi",
    "customer_id": 2424,
    "status": "new",
    "traffic_congestion_zone": false,
    "traffic_odd_even_zone": false,
    "launched_at": "2018-12-11T12:34:14+03:30",
    "city": "tehran",
    "delay": 0,
    "price": 33500,
    "credit": true,
    "cashed": false,
    "has_return": false,
    "distance": 23022,
    "duration": 2841,
    "invoice_number": "F19963",
    "pay_at_dest": false,
    "device_id": null,
    "weight": 0,
    "is_api": false,
    "is_vip": false,
    "updated_at": "2018-12-11T12:34:14+03:30",
    "created_at": "2018-12-11T12:34:14+03:30",
    "id": 19285,
    "signature": {
      "url": "/uploads/order/19285/signature.jpg?var=1544519054"
    },
    "order_token": "15dc6db1819285g1837d6dcb1f744g2424206063948",
    "nprice": null,
    "subsidy": null,
    "signed_by": "",
    "final_price": 33500,
    "addresses": [
      {
        "id": 590602,
        "order_id": 19285,
        "customer_id": 2424,
        "courier_id": null,
        "lat": 35.75678,
        "lng": 51.411255,
        "type": "origin",
        "priority": 0,
        "city": "tehran",
        "status": "pending",
        "address": "تهران، منطقه ۳، کاووسیه، خ گاندی، خ بیستم",
        "description": "some description for origin",
        "unit": "unit of origin address",
        "number": "number of origin address",
        "person_fullname": "sender s name",
        "person_phone": "sender s phone",
        "signed_by": null,
        "distance": null,
        "google_distance": null,
        "duration": null,
        "google_duration": null,
        "arrived_at": null,
        "handled_at": null,
        "created_at": "2018-12-11T12:34:14+03:30",
        "updated_at": "2018-12-11T12:34:14+03:30",
        "deleted_at": null,
        "arrive_lat": null,
        "arrive_lng": null,
        "handle_lat": null,
        "handle_lng": null,
        "signature": null,
        "city_fa": "تهران"
      },
      {
        "id": 590605,
        "order_id": 19285,
        "customer_id": 2424,
        "courier_id": null,
        "lat": 35.758495,
        "lng": 51.44255,
        "type": "destination",
        "priority": 1,
        "city": "tehran",
        "status": "pending",
        "address": "منطقه ۳، داودیه، میرداماد جنوبی، م مادر ابتدای خ بهروز",
        "description": "some description for destination",
        "unit": "unit of destination address",
        "number": "number of destination address",
        "person_fullname": "receiver s name",
        "person_phone": "receiver s phone",
        "signed_by": null,
        "distance": 2830,
        "google_distance": null,
        "duration": 349,
        "google_duration": null,
        "arrived_at": null,
        "handled_at": null,
        "created_at": "2018-12-11T12:34:14+03:30",
        "updated_at": "2018-12-11T12:34:14+03:30",
        "deleted_at": null,
        "arrive_lat": null,
        "arrive_lng": null,
        "handle_lat": null,
        "handle_lng": null,
        "signature": null,
        "city_fa": "تهران"
      },
      {
        "id": 590608,
        "order_id": 19285,
        "customer_id": 2424,
        "courier_id": null,
        "lat": 35.895452,
        "lng": 51.589632,
        "type": "destination",
        "priority": 2,
        "city": "tehran",
        "status": "pending",
        "address": "بخش رودبارقصران، روستای امامه پایین",
        "description": "some description for destination",
        "unit": "unit of destination address",
        "number": "number of destination address",
        "person_fullname": "receiver s name",
        "person_phone": "receiver s phone",
        "signed_by": null,
        "distance": 20192,
        "google_distance": null,
        "duration": 2492,
        "google_duration": null,
        "arrived_at": null,
        "handled_at": null,
        "created_at": "2018-12-11T12:34:14+03:30",
        "updated_at": "2018-12-11T12:34:14+03:30",
        "deleted_at": null,
        "arrive_lat": null,
        "arrive_lng": null,
        "handle_lat": null,
        "handle_lng": null,
        "signature": null,
        "city_fa": "تهران"
      }
    ],
    "order_discount": null,
    "orderDiscount": null
  }
}

Once you calculated the price of your order, you can use this endpoint in order to create a new order.

HTTP Request

POST https://sandbox-api.alopeyk.com/api/v2/orders

Request Parameters

Parameter Default Required Description
transport_type NULL true The transport type of the order. Current valid values for this attribute are motorbike for simple package delivery, motor_taxi for passenger transportions, cargo for cargo, cargo_s for Small Cargo, and car for Car transportations.
addresses[0][type] NULL true Must be of type origin.
addresses[0][lat] NULL true Latitude of the origin address.
addresses[0][lng] NULL true Longitude of the origin address.
addresses[0][description] NULL false The description of the address which must be of type text.
addresses[0][unit] NULL false Exact unit number of the address.
addresses[0][number] NULL false Exact building number of the destination address.
addresses[0][person_fullname] NULL false Full name of the person receiving the package or the person residing at that address.
addresses[0][person_phone] NULL false Phone number of the person receiving the package or the person residing at that address.
addresses[1][type] NULL true Must be of type destination.
addresses[1][lat] NULL true Latitude of the first destination address.
addresses[1][lng] NULL true Longitude of the first destination address.
addresses[1][description] NULL false The description of the address which must be of type text.
addresses[1][unit] NULL false Exact unit number of the address.
addresses[1][number] NULL false Exact building number of the destination address.
addresses[1][person_fullname] NULL false Full name of the person receiving the package or the person residing at that address.
addresses[1][person_phone] NULL false Phone number of the person receiving the package or the person residing at that address.
addresses[2][type] NULL false Must be destination.
addresses[2][lat] NULL false Latitude of the extra destination addresses.
addresses[2][lng] NULL false Longitude of the extra destination addresses.
addresses[2][description] NULL false The description of the address which must be of type text.
addresses[2][unit] NULL false Exact unit number of the address.
addresses[2][number] NULL false Exact building number of the destination address.
addresses[2][person_fullname] NULL false Full name of the person receiving the package or the person residing at that address.
addresses[2][person_phone] NULL false Phone number of the person receiving the package or the person residing at that address.
has_return false false If you are going to calculate price for an order which has a return option, set it to true.
scheduled_at NULL false A timestamp that decides whether you would like to create a scheduled order which will be launched at you desired date and time.
cashed false false If you are going to force the payment type as cash, set it to true.
extra_params NULL false A JSON object allowing your database to be mapped with AloPeyk’s orders (ex : { my_order_id : 3333 } ). This object is returned on each webhook call.

Response Descriptions

Attribute Description
id The ID of the order
invoice_number Order’s Invoice Number (5 random chars).
customer_id The ID of the customer.
order_token The unique token of the order (for the tracking page).
status Status of the order. See Order Statuses section for a complete list of possible statuses.
accept_lat Source Latitude.
accept_lng Source Longitude.
price Price of the order.
credit Payment type of the Order (cash or credit).
distance Estimated distance between the source and the destination (Provided by Google ETA).
duration Estimated duration for path between the source and the destination. (Based on Google Distance Matrix ETA)
progress Current progress of the order on a scale of 0 to 1.
signature Signature of the order. This attribute will be NULL until the delivered status.
screenshot Screenshot of the order (Link of the screenshot).
launched_at Once the order is launched, this will be the same as the created_at attribute if the order is not scheduled.
updated_at The last timestamp when the order has been updated.
created_at The timestamp when the order was created.

GET
Get Order Detail

curl 'https://sandbox-api.alopeyk.com/api/v2/orders/{$order_id}?columns=*,addresses,screenshot,progress,courier,customer,last_position_minimal,eta_minimal' \
  -X GET \
  -H 'Authorization: Bearer {$token}' \
  -H 'X-Requested-With: XMLHttpRequest'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://sandbox-api.alopeyk.com/api/v2/orders/{$order_id}?columns=*,addresses,screenshot,progress,courier,customer,last_position_minimal,eta_minimal",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING       => "",
  CURLOPT_MAXREDIRS      => 10,
  CURLOPT_TIMEOUT        => 30,
  CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST  => "GET",
  CURLOPT_HTTPHEADER     => [
    "Authorization: Bearer " . $token,
    "X-Requested-With: XMLHttpRequest"
  ],
]);

$response = curl_exec($curl);
$err      = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}
var data = null;

var xhr = new XMLHttpRequest();

xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open('GET', 'https://sandbox-api.alopeyk.com/api/v2/orders/{order_id}?columns=*,addresses,screenshot,progress,courier,customer,last_position_minimal,eta_minimal');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.send(data);

The above command returns a JSON response structured like this:

{
    "status": "success",
    "message": null,
    "object": {
        "id": 14756,
        "invoice_number": "DKCA47",
        "customer_id": 86,
        "device_id": null,
        "courier_id": 3135,
        "cancelled_by": null,
        "status": "picking",
        "distance": 23022,
        "duration": 2841,
        "price": 33500,
        "credit": false,
        "cashed": false,
        "has_return": false,
        "pay_at_dest": false,
        "delay": 0,
        "is_vip": 0,
        "transport_type": "motorbike",
        "city": "tehran",
        "is_api": true,
        "weight": 20,
        "traffic_odd_even_zone": 0,
        "traffic_congestion_zone": 0,
        "accept_lat": 35.755289393991,
        "accept_lng": 51.415370104546,
        "rate": 0,
        "comment": null,
        "scheduled_at": null,
        "launched_at": "2018-10-24T14:21:45+03:30",
        "accepted_at": "2018-10-24T14:21:49+03:30",
        "delivered_at": null,
        "finished_at": null,
        "stopped_at": null,
        "removed_at": null,
        "created_at": "2018-10-24T14:21:45+03:30",
        "updated_at": "2018-10-24T14:22:07+03:30",
        "deleted_at": null,
        "picking_at": "2018-10-24T14:22:07+03:30",
        "delivering_at": null,
        "addresses": [
            {
                "lat": "35.75678",
                "lng": "51.411255",
                "type": "origin",
                "priority": 0,
                "arrived_at": "2018-10-24T14:22:07+03:30",
                "handled_at": "",
                "id": 28722,
                "city": "tehran",
                "order_id": "14756",
                "customer_id": "86",
                "courier_id": "3135",
                "status": "arrived",
                "address": "address of order s origin",
                "description": "some description for origin",
                "unit": "unit of origin address",
                "number": "number of origin address",
                "person_fullname": "sender s name",
                "person_phone": "sender s phone",
                "signed_by": "",
                "distance": "407",
                "duration": "50",
                "created_at": "2018-10-24T14:21:45+03:30",
                "updated_at": "2018-10-24T14:22:07+03:30",
                "deleted_at": "",
                "arrive_lat": "35.755285142037565",
                "arrive_lng": "51.41538546378716",
                "handle_lat": "",
                "handle_lng": "",
                "signature": null,
                "city_fa": "تهران"
            },
            {
                "lat": "35.758495",
                "lng": "51.44255",
                "type": "destination",
                "priority": 1,
                "arrived_at": "",
                "handled_at": "",
                "id": 28723,
                "city": "tehran",
                "order_id": "14756",
                "customer_id": "86",
                "courier_id": "3135",
                "status": "pending",
                "address": "address of order s destination",
                "description": "some description for destination",
                "unit": "unit of destination address",
                "number": "number of destination address",
                "person_fullname": "receiver s name",
                "person_phone": "receiver s phone",
                "signed_by": "",
                "distance": "2830",
                "duration": "349",
                "created_at": "2018-10-24T14:21:45+03:30",
                "updated_at": "2018-10-24T14:21:49+03:30",
                "deleted_at": "",
                "arrive_lat": "",
                "arrive_lng": "",
                "handle_lat": "",
                "handle_lng": "",
                "signature": null,
                "city_fa": "تهران"
            },
            {
                "lat": "35.895452",
                "lng": "51.589632",
                "type": "destination",
                "priority": 2,
                "arrived_at": "",
                "handled_at": "",
                "id": 28724,
                "city": "tehran",
                "order_id": "14756",
                "customer_id": "86",
                "courier_id": "3135",
                "status": "pending",
                "address": "address of order s destination",
                "description": "some description for destination",
                "unit": "unit of destination address",
                "number": "number of destination address",
                "person_fullname": "receiver s name",
                "person_phone": "receiver s phone",
                "signed_by": "",
                "distance": "20192",
                "duration": "2492",
                "created_at": "2018-10-24T14:21:45+03:30",
                "updated_at": "2018-10-24T14:21:49+03:30",
                "deleted_at": "",
                "arrive_lat": "",
                "arrive_lng": "",
                "handle_lat": "",
                "handle_lng": "",
                "signature": null,
                "city_fa": "تهران"
            }
        ],
        "screenshot": {
            "url": "https://sandbox-api.alopeyk.com/api/v2/screenshots?markers=origin,35.75678,51.411255|destination,35.758495,51.44255|destination,35.895452,51.589632"
        },
        "progress": "0.2857",
        "courier": {
            "id": 3135,
            "phone": "01234567891",
            "firstname": "AAAAAA",
            "lastname": "BBBBBB",
            "email": "",
            "referral_code": "HDTXR",
            "avatar": {
                "url": "/uploads/user/3135/avatar.jpg?var=1540378328"
            },
            "abs_avatar": {
                "url": "https://api.alopeyk.com/uploads/user/3135/avatar.jpg?var=1540378328"
            },
            "last_online": null,
            "is_online": null
        },
        "customer": {
            "id": 86,
            "phone": "01234567891",
            "firstname": "AAAAAA",
            "lastname": "BBBBBB",
            "email": "aaabbb@yourdomain.com",
            "referral_code": "P9K6A",
            "avatar": {
                "url": "/uploads/user/86/avatar.jpg?var=1540378328"
            },
            "abs_avatar": {
                "url": "https://api.alopeyk.com/uploads/user/86/avatar.jpg?var=1540378328"
            },
            "last_online": null,
            "is_online": null
        },
        "last_position_minimal": {
            "id": 1224,
            "courier_id": 3135,
            "lat": 35.755286079204,
            "lng": 51.415403016532,
            "updated_at": "2018-10-24 14:22:02",
            "last_update": "6 seconds ago"
        },
        "eta_minimal": {
            "id": 469,
            "last_position_id": 1224,
            "duration": 154,
            "distance": 1527,
            "action": "accept",
            "address_id": "28722",
            "updated_at": "2018-10-24 14:21:49"
        },
        "signature": {
            "url": "/uploads/order/14756/signature.jpg?var=1540378329"
        },
        "order_token": "4f0de6e7514756g18fb7c98191c4eg860c6778a42",
        "nprice": null,
        "subsidy": null,
        "signed_by": "",
        "final_price": 33500
    }
}

In order to get the order details, call this endpoint.

HTTP Request

GET https://sandbox-api.alopeyk.com/api/v2/orders/{order_id}

URL Parameters

Parameter Default Required Description
order_id NULL true Order ID

Response Descriptions

Attribute Description
id ID of the order.
invoice_number The unique invoice number of the order for later references.
customer_id Your ID.
device_id The ID of the device used to create the order.
order_token The unique token of the order.
status Status of the order. See Order Statuses section for a complete list of possible statuses.
price Price of the order.
credit Payment type of the order.
cashed Payment type of the order.
has_return Determine if the order has a return option which indicates whether the courier has to return to the origin address after handling the final address.
pay_at_dest Determine whether the order must be paid for at the destination address.
distance Estimated distance between the source and the destination.
duration Estimated duration for the path between the source and the destination.
accept_lat Latitude of the position where courier has accepted the order.
accept_lng Longitude of the position where courier has accepted the order.
accept_duration Estimated duration for the path between the source and the position where courier has accepted the order.
accept_distance Estimated distance between the source and the position where courier has accepted the order.
rate The rating you give the courier after you finish the order.
comment Your comment on the order which can be filled when you finish or cancel the order, or by the support team on the event of order cancellation.
progress Current Progress of the order on a scale of 0 to 1.
signature Signature of the order. This attribute will be NULL until the last address is handled.
screenshot Screenshot of the order progress on the map.
launched_at When the order has been launched, this will be same as created_at attribute if the order does not have a scheduled status.
updated_at The last timestamp the order has been updated.
created_at The timestamp when the order has been created.
courier This object contains the information of the courier who has accepted the order. Including his phone, firstname, lastname, avatar, abs_avatar. In this object, the avatar key refers to the relative path to your avatar and abs_avatar is the absolute path. Note that {user_id} in the URL will be replaced by the ID of the courier or the customer depending on who this object belongs to.
customer This is your user object.
last_position_minimal The compact version of the last recorded position of the courier who has accepted the order. This compact version includes the ID of the order as id, the ID of the courier as courier_id, the last recorded latitude and longitude of the courier as lat and lng, and finally updated_at as the last timestamp this object has recorded any changes.

GET
Cancel Order

curl 'https://sandbox-api.alopeyk.com/api/v2/orders/{$order_id}/cancel' \
  -X GET \
  -H 'Authorization: Bearer {$token}' \
  -H 'X-Requested-With: XMLHttpRequest'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://sandbox-api.alopeyk.com/api/v2/orders/{$order_id}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING       => "",
  CURLOPT_MAXREDIRS      => 10,
  CURLOPT_TIMEOUT        => 30,
  CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST  => "GET",
  CURLOPT_HTTPHEADER     => [
    "Authorization: Bearer " . $token,
    "X-Requested-With: XMLHttpRequest"
  ],
]);

$response = curl_exec($curl);
$err      = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}
var data = null;

var xhr = new XMLHttpRequest();

xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open('GET', 'https://sandbox-api.alopeyk.com/api/v2/orders/{order_id}/cancel');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.send(data);

The above command returns a JSON response structured like this:

{
  "status": "success",
  "message": null,
  "object": {
    "id": 14757,
    "status": "cancelled",
    "courier_id": 3136,
    "customer_id": 86,
    "signature": {
      "url": "/uploads/order/14757/signature.jpg?var=1540380369"
    },
    "order_token": null,
    "nprice": null,
    "subsidy": null,
    "signed_by": "",
    "final_price": null
  }
}

You can cancel any order before courier arrival (before the accepted status)

HTTP Request

GET https://sandbox-api.alopeyk.com/api/v2/orders/{order_id}/cancel

URL Parameters

Parameter Default Required Description
order_id NULL true Order ID.

POST
Webhooks

{
  "order": {
    "id": 263197,
    "invoice_number": "4NTNKF",
    "status": "accepted",
    "city": "tehran",
    "transport_type": "motor_taxi",
    "delay": 0,
    "distance": 22533,
    "duration": 2780,
    "price": 31500,
    "credit": false,
    "cashed": false,
    "has_return": false,
    "pay_at_dest": false,
    "accept_lat": 35.754097,
    "accept_lng": 51.415339,
    "signature": null,
    "screenshot": {
      "url": "https://screenshots.alopeyk.com/?size=640x330&maptype=roadmap&language=fa&markers=icon:https://api.alopeyk.com/images/marker-origin.png%7C35.75546,51.416874&markers=icon:https://api.alopeyk.com/images/marker-destination.png%7C35.758495,51.44255&markers=icon:https://api.alopeyk.com/images/marker-destination.png%7C35.895452,51.589632"
    },
    "progress": "0.1429",
    "order_token": be5c4b781263197g86cc78fa6b1a2fg2526b18ac75a,
    "tracking_url": "http://tracking.alopeyk.com/#/be5c4b781263197g86cc78fa6b1a2fg2526b18ac75a",
    "cancelled_by": null,
    "scheduled_at": null,
    "launched_at": "2017-09-12T18:45:39+04:30",
    "accepted_at": "2017-09-12T18:49:34+04:30",
    "picking_at": null,
    "delivering_at": null,
    "delivered_at": null,
    "finished_at": null,
    "stopped_at": null,
    "created_at": "2017-09-12T18:45:39+04:30",
    "updated_at": "2017-09-12T18:49:34+04:30",
    "addresses": [
      {
        "lat": "35.75546",
        "lng": "51.416874",
        "type": "origin",
        "priority": 0,
        "arrived_at": "",
        "handled_at": "",
        "id": 547412,
        "city": "tehran",
        "order_id": "263197",
        "customer_id": 1111111111111,
        "courier_id": 222222222222,
        "status": "pending",
        "address": "address of order s origin",
        "description": "some description for origin",
        "unit": "unit of origin address",
        "number": "number of origin address",
        "person_fullname": "sender s name",
        "person_phone": "sender s phone",
        "signed_by": "",
        "distance": "205",
        "duration": "25",
        "created_at": "2017-09-12T18:45:39+04:30",
        "updated_at": "2017-09-12T18:49:36+04:30",
        "deleted_at": "",
        "arrive_lat": "",
        "arrive_lng": "",
        "handle_lat": "",
        "handle_lng": "",
        "signature": null
      },
      {
        "lat": "35.758495",
        "lng": "51.44255",
        "type": "destination",
        "priority": 1,
        "arrived_at": "",
        "handled_at": "",
        "id": 547413,
        "city": "tehran",
        "order_id": "263197",
        "customer_id": 1111111111111,
        "courier_id": 222222222222,
        "status": "pending",
        "address": "address of order s destination",
        "description": "some description for destination",
        "unit": "unit of destination address",
        "number": "number of destination address",
        "person_fullname": "receiver s name",
        "person_phone": "receiver s phone",
        "signed_by": "",
        "distance": "2341",
        "duration": "288",
        "created_at": "2017-09-12T18:45:39+04:30",
        "updated_at": "2017-09-12T18:49:34+04:30",
        "deleted_at": "",
        "arrive_lat": "",
        "arrive_lng": "",
        "handle_lat": "",
        "handle_lng": "",
        "signature": null
      },
      {
        "lat": "35.895452",
        "lng": "51.589632",
        "type": "destination",
        "priority": 2,
        "arrived_at": "",
        "handled_at": "",
        "id": 547414,
        "city": "tehran",
        "order_id": "263197",
        "customer_id": 1111111111111,
        "courier_id": 222222222222,
        "status": "pending",
        "address": "address of order s destination",
        "description": "some description for destination",
        "unit": "unit of destination address",
        "number": "number of destination address",
        "person_fullname": "receiver s name",
        "person_phone": "receiver s phone",
        "signed_by": "",
        "distance": "20192",
        "duration": "2492",
        "created_at": "2017-09-12T18:45:39+04:30",
        "updated_at": "2017-09-12T18:49:34+04:30",
        "deleted_at": "",
        "arrive_lat": "",
        "arrive_lng": "",
        "handle_lat": "",
        "handle_lng": "",
        "signature": null
      }
    ],
    "courier": {
      "phone": "01234567891",
      "firstname": "AAAAAA",
      "lastname": "BBBBBB",
      "avatar": {
        "url": "/uploads/user/{user_id}/avatar.jpg?var=1497182505"
      },
      "abs_avatar": {
        "url": "https://api.alopeyk.com/uploads/user/{user_id}/avatar.jpg?var=1497182505"
      },
      "last_position": {
        "lat": 35.754098,
        "lng": 51.415349,
      },
    },
    "eta_minimal": {
      "duration": 60,
      "distance": 551,
      "address_id": 547412,
      "updated_at": "2017-09-12 18:49:36",
    }
  }
}

In order to receive your orders real-time updates, we recommend using our HTTP Webhooks. By providing us with a URL, we will be able to send the latest order payload via POST method to the provided URL (Webhook) on each status change.

We will send the order object including the courier’s position if any, as the POST request body with the following generic structure:

Your Webhook API Looks Like

POST http(s)://www.example.com/my/orders/webhook

Structure Descriptions

Attribute Description
id The ID of the order
invoice_number The order’s Invoice Number (5 random chars).
accept_lat Source Latitude.
accept_lng Source Longitude.
status Status of the order. See the Order Statuses section for a complete list of possible statuses.
distance Estimated distance between the source and the destination. (provided by Google ETA)
duration Estimated duration for the path between the source and the destination. (Based on Google Distance Matrix ETA)
price Price of the order.
credit Payment type of the order (cash or credit).
cashed Indicates whether the payment type of order has been forced to cash or not.
progress Current Progress of the order on a scale of 0 to 1.
signature Signature of the order. This attribute will be NULL until the last destination is handled and signed.
screenshot Screenshot of the order progress on the map.
has_return Indicates whether the order has a return option.
pay_at_dest Indicates whether the order must be paid for at the destination address.
courier Order’s courier object, including phone, firstname and lastname. We have also included the latitude and longitude of the courier’s last position on this object.
order_token The unique token generated for that specific order.
tracking_url The sharable tracking URL for that specific order.
launched_at When the order has been launched, this will be the same as the created_at attribute (if the order is not a scheduled order).
updated_at The last timestamp when the order has been updated.
created_at The timestamp when the order has been created.
extra_param An object of the extra parameters you can set for your webhook requests when creating new orders.

Statuses

Status Description
new The order has been created and is ready to be dispatched to the nearest courier available.
searching The dispatcher machine is currently looking for near-by available couriers and is waiting for them to accept the order.
cancelled The order has been cancelled. if this event takes place by the customer it has to be before the picking status otherwise it means that the support team has cancelled the order.
expired No available courier was found for the order or no courier has responded or accepted your request
accepted One of our couriers has accepted the order.
picking The courier has arrived at the source of the order which is in fact the first address (the origin).
delivering The courier has successfuly handled the first address and is now delivering the package(s).
delivered The courier successfully dropped all packages at their designated addresses i.e. the courier has handled those addresses.
finished This status is not required. You can finish the order and rate our courier in which case the rate and comment attributes will be filled by you while updating the order to this status.
scheduled This status is specific to the scheduled orders. Once the scheduled_at timestamp is reached, the order will be dispatched automatically and its status will be updated to new. From this stage the orders will follow the same routine listed above.

GET
Tracking

Once you successfully have created an order, you will be able to watch the courier on a live map.

At Sandbox environment, courier location is static and order status will change every 30 seconds. But at Production environment, the courier location and order status based on reality will be change.

You can access tracking URL (tracking_url) trough Webhook data. Even you can manually create this URL by concatenation Order Token (‘order_token’) which is accessible in Order details method and the tracking base URL

https://sandbox-tracking.alopeyk.com/#/<order_token>

For customizing some elements, you can pass these variables on a URL by GET method

Parameter Type Description
logo URL Replace default “alopeyk logo” with your custom logo.
customer_image URL Replace your alopeyk profile image with your own customer image.
customer_name String Replace your alopeyk profile name with your own customer name.
show_payment_status Boolean By sending false for this variable, you can hide payment status.
show_order_price Boolean By sending false for this variable as value, you can hide order price box.
show_courier_phone Boolean By sending false for this variable, you can hide courier phone number.
show_order_info_box Boolean By sending false for this variable as value, you can hide order info box.

POST
Rate Order

curl 'https://sandbox-api.alopeyk.com/api/v2/orders/{$order_id}/finish' \
  -X POST \
  -H 'Authorization: Bearer {$token}' \
  -H 'X-Requested-With: XMLHttpRequest' \
  -H 'Content-Type: application/json; charset=utf-8' \
  --DATA '{"rate":5,"comment":"Amazing! Your API is excellent. Thanks."}'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://sandbox-api.alopeyk.com/api/v2/orders/{$order_id}/finish",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING       => "",
  CURLOPT_MAXREDIRS      => 10,
  CURLOPT_TIMEOUT        => 30,
  CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST  => "POST",
  CURLOPT_POSTFIELDS     => json_encode(
    [
      "rate"    => 5,
      "comment" => "Amazing! Your API is excellent. Thanks."
    ]
  ),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . $token,
    "X-Requested-With: XMLHttpRequest"
  ],
]);

$response = curl_exec($curl);
$err      = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}
var data = JSON.stringify({
  'rate': 5,
  'comment': 'Amazing! Your API is excellent. Thanks.'
});

var xhr = new XMLHttpRequest();

xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open('POST', 'https://sandbox-api.alopeyk.com/api/v2/orders/{order_id}/finish');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader('Content-Type', 'application/json; charset=utf-8');

xhr.send(data);

The above command returns a JSON response structured like this:

{
    "status": "success",
    "message": null,
    "object": {
        "id": 11111,
        "status": "finished",
        "courier_id": 2222,
        "customer_id": 11,
        "accepted_at": "2018-10-27T13:14:42+03:30",
        "city": "tehran",
        "transport_type": "motorbike",
        "price": 26000,
        "rate": 5,
        "next_address_any": null,
        "signature": {
            "url": "/uploads/order/14817/signature.jpg?var=1540634493"
        },
        "order_token": null,
        "nprice": null,
        "subsidy": null,
        "signed_by": "",
        "final_price": 26000
    }
}

When an order is in its final status (delivered or returned due to the order’s has_return attribute), you can call this endpoint, to fill the rate and the comment attributes.

HTTP Request

POST https://sandbox-api.alopeyk.com/api/v2/orders/{order_id}/finish

URL Parameters

Parameter Default Required Description
order_id NULL true Order ID

Request Parameters

Parameter Default Required Description
rate NULL false Your Rating on the order. Must be an integer in the range of 1-5.
comment NULL false Your comment on the order. Must be of type text.

PUT
Edit Order

curl 'https://sandbox-api.alopeyk.com/api/v2/orders/{$order_id}' \
  -X PUT \
  -H 'Authorization: Bearer {$token}' \
  -H 'X-Requested-With: XMLHttpRequest'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://sandbox-api.alopeyk.com/api/v2/orders/{$order_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING       => "",
  CURLOPT_MAXREDIRS      => 10,
  CURLOPT_TIMEOUT        => 30,
  CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST  => "PUT",
  CURLOPT_POSTFIELDS     => json_encode(
    [
      "has_return": false,
      "cashed": false,
      "credit": true,
      "pay_at_dest": false,
      "delay": 20,
      "transport_type": "motorbike"
    ]
  ),
  CURLOPT_HTTPHEADER     => [
    "Authorization: Bearer " . $token,
    "X-Requested-With: XMLHttpRequest",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err      = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}
var data = null;

var xhr = new XMLHttpRequest();

xhr.addEventListener('readystatechange', function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open('PUT', 'https://sandbox-api.alopeyk.com/api/v2/orders/{order_id}');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.send(data);

The above command returns a JSON response structured like Get Order Detail.

For order editions and updates, transport types of the same group can be changed to each other. This means that the transport types of motor orders can not be changed into transport types belonging to car or cargo group.

If an order has a return policy and courier has started the trip back the origin address. The has_return parameter cannot be turned off. In order to edit the order details, this endpoint can be called:

HTTP Request

PUT https://sandbox-api.alopeyk.com/api/v2/orders/{order_id}

URL Parameters

Parameter Default Required Description
order_id NULL true Order ID

Request Parameters

Parameter Default Required Description
has_return NULL false If your order needs to be returned to the origin, you can apply it by sending the true for this option before announcing the end of the order by the courier.
cashed&credit NULL false If you want to change the payment type, you can use these two options. One of these two options should always be true and other one false.
pay_at_dest NULL false If the cashed option is true, by set this option to true the order price can be paid at destination. This option is available only for single-destination trips.
delay NULL false You can apply a integer value in minutes to add a stop time in the locations. If set to this option, you can not reduce it and you can only increase its value.
transport_type NULL false Depending on the section of the groups in the above description, you can change the option to change the type of trip.

Errors

Error Code Meaning
400 Bad Request – Your request is invalid.
401 Unauthorized – Your JWT token is invalid.
403 Forbidden – You do not enough permissions to perform this action.
404 Not Found – The specified resource could not be found.
405 Method Not Allowed – You tried to access an API endpoint with an invalid REST method.
406 Not Acceptable – You requested by a format that isn’t JSON.
410 Gone – The requested resource has been removed from our servers.
429 Too Many Requests – You’re requesting too many resources.
500 Internal Server Error – We had a problem with our server. Try again later.
502 Bad Gateway – The server cant handle your request for the moment. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

In this case response code is 200, but it still indicates an error.

Error Const Meaning
UNKNOWN_ERROR An unknown reason prevented us to perform the action you have requested.
FORBIDDEN_ERROR You are going to perform an action which is not allowed.
INVALID_REQUEST_ERROR You have sent an invalid request.
ORDER_NOT_FOUND_ERROR The order on which you are going to perform an action was not found.
ORDER_CANCELLED_ERROR The order on which you are going to perform an action has been already cancelled.
USER_MINUS_CREDIT_ERROR Your account credit has gone under zero, so you can’t create a new order.
LIMIT_EXCEEDED_ERROR Your current active (not finished) orders count has exceeded our limit, so you can’t create a new one until you finish one of them.