NAV Navbar
Logo
shell php javascript

Introduction

Using the AloPeyk’s API, businesses can easily integrate our on-demand delivery service into their platform whether is an E-Commerce (Magento, Prestashop, OpenCart, WooCommerce, etc) or is a Mobile App.

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

Basics

AloPeyk’s API is fully REST based :

Environments

Sandbox environment provides driver bots acting like real couriers (accepting orders, drive from origin to destination, etc) so you can test your implementation in “production-like” conditions.

Below you can find different steps for Order completion:

1- Accepting Order ( accept ): Maximum 10 seconds after Order Creation.

2- Arriving to Source Address ( at_source ): 1 minute after prev step.

3- Picking Up The Package ( pickup ): 1 minute after prev step.

4- Arriving at Destination ( at_destination ): 1 minute after prev step.

5- Dropping the Package ( drop ): 1 minute after prev step.

4- Returning to the Source Address ( returned if the Order has return option ): 1 minute after prev step.

API Rate Limits

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

Our main limit factors are Request Per Minute and Request Per Day. If you overcome any of those two Rate Limits you’re access will be limited blocked for that time window, so you’ll have to wait until the time window is over.

Minute Rate Limit

Currently you can consume 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 consume 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

For Authentication, use this code:

curl "https://sandbox-api.alopeyk.com/api/v1/" \
  -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/v1/',
  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/v1/');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.send(data);

Make sure to replace $token with your JWT Token.

All Alopeyk API endpoints support JWT authentication protocol.

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

Since you have a valid token you need to add it as a 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 returned will have a long expiration time ( might be limited in the future ), and won’t be expired until you request a new token.

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

Location

Get Address

curl "https://sandbox-api.alopeyk.com/api/v1/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/v1/locations?latlng=35.755484%2C51.415306',
  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/v1/locations?latlng=35.755484%2C51.415306');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.send(data);

The above command returns JSON structured like this:

{
  "status": "success",
  "message": "findPlace",
  "object": {
    "address": [
      "ناوک",
      "بزرگراه آفریقا"
    ],
    "region": "ونک"
  }
}

This endpoint retrieves place information by its latitude and longitude.

HTTP Request

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

Query Parameters

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

Location Suggestions

curl 'https://sandbox-api.alopeyk.com/api/v1/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/v1/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/v1/locations?input=میرداماد');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.send(data);

The above command returns JSON structured like this:

{
  "status": "success",
  "message": "autoComplete",
  "object": [
    {
      "title": "میرداماد",
      "region": "داودیه",
      "lat": "35.760743499999997",
      "lng": "51.426777299999998"
    },
    {
      "title": "میرداماد",
      "region": "داودیه",
      "lat": "35.759472449999997",
      "lng": "51.43739935"
    },
    {
      "title": "میرداماد",
      "region": "داودیه",
      "lat": "35.758719800000001",
      "lng": "51.443581600000002"
    },
    {
      "title": "میرداماد",
      "region": "داودیه",
      "lat": "35.759170599999997",
      "lng": "51.443900800000002"
    },
    {
      "title": "بلوار میرداماد",
      "region": "داودیه",
      "lat": "35.759433547783097",
      "lng": "51.436231358821303"
    }
  ]
}

This endpoint retrieves suggestions by search input.

The result will be an array of suggestions, each one includes the region and name of the found place, and offers a coordination for the item.

HTTP Request

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

Query Parameters

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

Price

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

curl 'https://sandbox-api.alopeyk.com/api/v1/orders/price/calc' \
  -X POST \
  -H 'Authorization: Bearer {$token}' \
  -H 'X-Requested-With: XMLHttpRequest' \
  -H 'Content-Type: application/json; charset=utf-8' \
  --DATA '{"coords":{"from":{"lat":"35.755460","lng":"51.416874"},"to":{"lat":"35.758495","lng":"51.442550"}},"has_return":false}'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://sandbox-api.alopeyk.com/api/v1/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(
    array(
      'coords' => array(
        'from' => array(
          'lat' => 35.755460,
          'lng' => 51.416874,
        ),
        'to' => array(
          'lat' => 35.758495,
          'lng' => 51.442550,
        ),
      ),
      "has_return" => 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({
  'coords': {
    'from': {
      'lat': 35.755460,
      'lng': 51.416874,
    },
    'to': {
      'lat': 35.758495,
      'lng': 51.442550,
    },
  },
  'has_return': 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/v1/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": {
    "price": 5000,
    "credit": false,
    "distance": 2341,
    "duration": 288,
    "status": "OK",
    "user_credit": null,
    "price_with_return": 7000
  }
}

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

HTTP Request

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

Request Parameters

Parameter Default Required Description
coords[from][lat] NULL true Latitude of the source.
coords[from][lng] NULL true Longitude of the source.
coords[to][lat] NULL true Latitude of the destination.
coords[to][lng] NULL true Longitude of the destination.
has_return false false If you are going to calculate price for an order which has return option, set it true.
cashed false false If you are going to force payment type as cash, set it true.

Response Descriptions

Attribute Description
status Indicates that the calculation progress was successfull or not.
price Total Calculated Price.
credit Indicates payment type of Order ( credit or cash ). Will be true only if you have enough credit for the Order. In the case of credit lack, or cashed=true, this attribute will be false.
distance Estimated distance between source and destination (Powered by Google ETA).
duration Estimated duration of path between source and destination (Based on Google Distance Matrix ETA).
user_credit Your Current Credit (in Toman).
price_with_return Calculated price for Order, in case of has_return=true.

Orders

Create Order

curl 'https://sandbox-api.alopeyk.com/api/v1/orders' \
  -X POST \
  -H 'Authorization: Bearer {$token}' \
  -H 'X-Requested-With: XMLHttpRequest' \
  -H 'Content-Type: application/json; charset=utf-8' \
  --DATA '{"from_lat":35.7552995,"from_lng":51.4153701,"to_lat":35.758771652731,"to_lng":51.415371894836,"from_info":{"address":"address of order`s source","unit":"unit of address","number":"number of address","description":"some description","sender":{"firstname":"sender`s firstname","lastname":"sender`s lastname","phone":"09121111111"}},"to_info":{"address":"address of order`s destination","unit":"unit of address","number":"number of address","description":"some description","receiver":{"firstname":"receiver`s firstname","lastname":"receiver`s lastname","phone":"09121111111"}}}'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://sandbox-api.alopeyk.com/api/v1/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(
    array(
      'from_lat' => 35.7552995,
      'from_lng' => 51.4153701,
      'to_lat' => 35.758771652731,
      'to_lng' => 51.415371894836,
      'from_info' => array(
        'address' => 'address of order`s source',
        'unit' => 'unit of address',
        'number' => 'number of address',
        'description' => 'some description',
        'sender' => array(
          'firstname' => 'sender`s firstname',
          'lastname' => 'sender`s lastname',
          'phone' => '09121111111'
        )
      ),
      'to_info' => array(
        'address' => 'address of order`s destination',
        'unit' => 'unit of address',
        'number' => 'number of address',
        'description' => 'some description',
        'receiver' => array(
          'firstname' => 'receiver`s firstname',
          'lastname' => 'receiver`s lastname',
          'phone' => '09121111111'
        )
      )
    )
  ),
  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({
  "from_lat": 35.7552995,
  "from_lng": 51.4153701,
  "to_lat": 35.758771652731,
  "to_lng": 51.415371894836,
  "from_info": {
    "address": "address of order`s source",
    "unit": "unit of address",
    "number": "number of address",
    "description": "some description",
    "sender": {
      "firstname": "sender`s firstname",
      "lastname": "sender`s lastname",
      "phone": "09121111111"
    }
  },
  "to_info": {
    "address": "address of order`s destination",
    "unit": "unit of address",
    "number": "number of address",
    "description": "some description",
    "receiver": {
      "firstname": "receiver`s firstname",
      "lastname": "receiver`s lastname",
      "phone": "09121111111"
    }
  }
});

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/v1/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 JSON structured like this:

{
  "status": "success",
  "message": null,
  "object": {
    "from_lat": "35.7552995",
    "from_lng": "51.4153701",
    "to_lat": "51.415371894836",
    "to_lng": "35.758771652731",
    "from_info": {
      "address": "address of order's source",
      "unit": "unit of address",
      "number": "number of address",
      "description": "some description",
      "sender": {
        "firstname": "sender's firstname",
        "lastname": "sender's lastname",
        "phone": "09121111111"
      }
    },
    "to_info": {
      "address": "address of order's source",
      "unit": "unit of address",
      "number": "number of address",
      "description": "some description",
      "signatory": "NULL",
      "receiver": {
        "firstname": "receiver's firstname",
        "lastname": "receiver's lastname",
        "phone": "09121111111"
      }
    },
    "customer_id": 252,
    "status": "start",
    "price": 5000,
    "credit": false,
    "distance": 386,
    "duration": 47,
    "invoice_number": "69172F",
    "launched_at": "2017-02-18 21:21:36",
    "device_id": null,
    "updated_at": "2017-02-18 21:21:36",
    "created_at": "2017-02-18 21:21:36",
    "id": 1983,
    "signature": {
      "url": "/uploads/order/1983/signature.jpg"
    },
    "screenshot": {
      "url": "http://screenshots.alopeyk.com/?size=640x330&maptype=roadmap&language=fa&markers=icon:https://alopeyk.com/media/home/app/courier-path/marker-origin.png%7C35.7552995,51.4153701&markers=icon:https://alopeyk.com/media/home/app/courier-path/marker-destination.png%7C51.415371894836,35.758771652731"
    },
    "progress": 0,
    "order_token": "d488e1dfb1986g4b372d362d5cd1g252441e70ee5"
  }
}

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

HTTP Request

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

Request Parameters

Parameter Default Required Description
from_lat NULL true Latitude of the source.
from_lng NULL true Longitude of the source.
to_lat NULL true Latitude of the destination.
to_lng NULL true Longitude of the destination.
from_info[address] NULL true Source Address.
from_info[unit] NULL false Source Address Unit.
from_info[number] NULL false Source Address Number.
from_info[description] NULL false Extra description.
from_info[sender][firstname] NULL false Sender`s firstname.
from_info[sender][lastname] NULL false Sender`s lastname.
from_info[sender][phone] NULL false Sender`s phone.
to_info[address] NULL true Source Address.
to_info[unit] NULL false Source Address Unit.
to_info[number] NULL false Source Address Number.
to_info[description] NULL false Extra description.
to_info[receiver][firstname] NULL false Sender`s firstname.
to_info[receiver][lastname] NULL false Sender`s lastname.
to_info[receiver][phone] NULL false Sender`s phone.

Response Descriptions

Attribute Description
id Order ID
invoice_number Order’s Invoice Number (5 random chars).
customer_id Customer ID.
order_token The unique token of the Order (for tracking page).
status Status of the Order. See Order Statuses section for complete list of possible statuses.
from_lat Source Latitude.
from_lng Source Longitude.
to_lat Destination Latitude.
to_lng Destination Longitude.
from_info Source Informations.
to_info Destination Informations.
price Price of the Order.
credit Payment type of the Order (Cash or Credit).
distance Estimated distance between source and destination (Powered by Google ETA).
duration Estimated duration for path between source and destination. (Based on Google Distance Matrix ETA)
progress Current Progress of the Order as percent (between 0 to 100).
signature Signature of the Order. This attribute will be NULL until drop status.
screenshot Screenshot of the Order (Link of the screenshot).
launched_at When the Order has been launched, this will be same as created_at attribute if the Order is not Scheduled.
updated_at The last time at which the Order has been updated.
created_at When the Order has been created.

Get Order Detail

curl 'https://sandbox-api.alopeyk.com/api/v1/orders/{$order_id}' \
  -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/v1/orders/{$order_id}',
  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/v1/orders/{order_id}');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.send(data);

The above command returns JSON structured like this:

{
  "status": "success",
  "message": null,
  "object": {
  "id": 1993,
  "invoice_number": "AC25L1",
  "customer_id": 252,
  "device_id": 268,
  "courier_id": 46,
  "from_lat": 35.7552995,
  "from_lng": 51.4153701,
  "to_lat": 35.758771652731,
  "to_lng": 51.415371894836,
  "from_info": {
    "address": "address of order`s source",
    "unit": "unit of address",
    "number": "number of address",
    "description": "some description",
    "sender": {
      "firstname": "sender`s firstname",
      "lastname": "sender`s lastname",
      "phone": "09121111111"
    }
  },
  "to_info": {
    "address": "address of order`s destination",
    "unit": "unit of address",
    "number": "number of address",
    "description": "some description",
    "receiver": {
      "firstname": "receiver`s firstname",
      "lastname": "receiver`s lastname",
      "phone": "09121111111"
    }
  },
  "status": "at_source",
  "distance": 386,
  "duration": 47,
  "price": 5000,
  "credit": false,
  "cashed": false,
  "has_return": false,
  "pay_at_dest": false,
  "accept_lat": 35.758771,
  "accept_lng": 51.415371,
  "accept_duration": 580,
  "accept_distance": 2450,
  "rate": 0,
  "comment": null,
  "status_log": "1487428743,1487429536",
  "broadcasteds": "46",
  "courier_cancel": false,
  "scheduled_at": null,
  "launched_at": "2017-02-19 12:40:56",
  "created_at": "2017-02-19 12:40:56",
  "updated_at": "2017-02-19 12:43:09",
  "deleted_at": null,
  "signature": null,
  "screenshot": {
    "url": "http://screenshots.alopeyk.com/?size=640x330&maptype=roadmap&language=fa&markers=icon:https://alopeyk.com/media/home/app/courier-path/marker-origin.png%7C35.7552995,51.4153701&markers=icon:https://alopeyk.com/media/home/app/courier-path/marker-destination.png%7C35.758771652731,51.415371894836"
  },
  "progress": 40,
  "order_token": "2d49d571b1993gd593d0dca785eag252fd83e7594"
  },
  "courier": {
    "phone": "09493516327",
    "firstname": "محمد رضا",
    "lastname": "نورشی",
    "avatar": {
      "url": "/uploads/user/46/avatar.jpg?var=1497181163"
    }
  },
  "customer": {
    "id": 252,
    "phone": "09498311367",
    "firstname": "Your First Name",
    "lastname": "Your Last Name",
    "type": "CUSTOMER",
    "email": null,
    "email_verified": 0,
    "verify": 1,
    "found_us": null,
    "referral_code": "9ANBH",
    "referred_by": "ASDKL",
    "created_at": "2017-02-19 12:30:30",
    "updated_at": "2017-02-19 12:30:30",
    "deleted_at": null,
    "rates_avg": "5.00",
    "orders_count": 33,
    "rates_0_count": 0,
    "rates_5_count": 15,
    "credit": null,
    "referredActiveCount": null,
    "referredIncome": null,
    "userTurnoverData": null,
    "userFilledOrdersData": null,
    "avatar": {
      "url": "/uploads/user/252/avatar.jpg?var=1497181163"
    }
  },
  "last_position": {
    "lat": 35.7552995,
    "lng": 51.4153701,
    "speed": 1,
    "updated_at": "2017-02-19 12:43:09"
  }
}

Due to get Orer details, call this endpoint.

HTTP Request

GET https://sandbox-api.alopeyk.com/api/v1/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 Invoice number of the Order.
customer_id Your id.
device_id The device id with which the Order was created.
order_token The unique token of the Order.
status Status of the Order. See Order Statuses section for complete list of possible statuses.
from_lat You sent it.
from_lng You sent it.
to_lat You sent it.
to_lng You sent it.
from_info You sent it.
to_info You sent it.
price Price of the Order.
credit Payment type of the Order.
cashed Payment type of the Order.
has_return Determine if the Order has / hasn’t return option.
pay_at_dest Determine if the Order’s cost must be paid at destination or not.
distance Estimated distance between source and destination.
duration Estimated duration for path between source and destination.
accept_lat Latitude of the position at which courier has accepted the order.
accept_lng Longitude of the position at which courier has accepted the order.
accept_duration Estimated duration for the path between source and the position at which courier has accepted the order.
accept_distance Estimated distance between source and the position at which courier has accepted the order.
rate Rate of the Order by you when you Finish the Order.
comment Comment of the Order, can be filled by your comment when you Finish/Cancel the Order, or by Support on Order Cancel.
status_log Timestamps on which the status of the Order was updated, this attribute is a comma seperated attributes with a timestamp for each completed status for example if the order is in pickup status, you will have 4 timestamps seperated with commas for start / accept / at_source / pickup statuses.
progress Current Progress of the Order as percent.
signature Signature of the Order. This attribute will be NULL until drop status.
screenshot Screenshot of the Order.
launched_at When the Order has been launched, this will be same as created_at attribute if the Order is not Scheduled.
updated_at The last time at which the Order has been updated.
created_at When the Order has been created.
courier This object is information of the courier who accepted the Order. Including phone, firstname, lastname, and the avatar.
customer This object is your user object.
last_position The last position info of the courier who accepted the Order. Including Latitude as lat, Longitude as lng, speed, and the last time the courier has updated his position, as updated_at.

Cancel Order

curl 'https://sandbox-api.alopeyk.com/api/v1/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/v1/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/v1/orders/{order_id}/cancel');
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.send(data);

The above command returns JSON structured like this:

{
  "status": "success",
  "message": null,
  "object": {
    "id": 1993,
    "invoice_number": "AC25L1",
    "customer_id": 252,
    "device_id": 268,
    "courier_id": 198,
    "from_lat": 35.7552995,
    "from_lng": 51.4153701,
    "to_lat": 35.758771652731,
    "to_lng": 51.415371894836,
    "from_info": {
      "address": "address of order`s source",
      "unit": "unit of address",
      "number": "number of address",
      "description": "some description",
      "sender": {
        "firstname": "sender`s firstname",
        "lastname": "sender`s lastname",
        "phone": "09121111111"
      }
    },
    "to_info": {
      "address": "address of order`s destination",
      "unit": "unit of address",
      "number": "number of address",
      "description": "some description",
      "receiver": {
        "firstname": "receiver`s firstname",
        "lastname": "receiver`s lastname",
        "phone": "09121111111"
      }
    },
    "status": "cancel",
    "distance": 386,
    "duration": 47,
    "price": 5000,
    "credit": false,
    "cashed": false,
    "has_return": false,
    "pay_at_dest": false,
    "accept_lat": 35.758771,
    "accept_lng": 51.415371,
    "accept_duration": 580,
    "accept_distance": 2450,
    "rate": 0,
    "comment": null,
    "status_log": "1487428743,1487429536",
    "broadcasteds": "198",
    "courier_cancel": false,
    "scheduled_at": null,
    "launched_at": "2017-02-19 12:40:56",
    "created_at": "2017-02-19 12:40:56",
    "updated_at": "2017-02-19 12:43:09",
    "deleted_at": null,
    "signature": null,
    "screenshot": {
      "url": "http://screenshots.alopeyk.com/?size=640x330&maptype=roadmap&language=fa&markers=icon:https://alopeyk.com/media/home/app/courier-path/marker-origin.png%7C35.7552995,51.4153701&markers=icon:https://alopeyk.com/media/home/app/courier-path/marker-destination.png%7C35.758771652731,51.415371894836"
    },
    "progress": 0,
    "order_token": "2d49d571b1993gd593d0dca785eag252fd83e7594"
  }
}

You can cancel any order before courier arrival (before at_source status)

HTTP Request

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

URL Parameters

Parameter Default Required Description
order_id NULL true Order ID.

Statuses

Status Description
start Order is created and sent to the nearest courier available.
cancel Order is cancelled by customer in that case it has to be before at_source status otherwise if the order is cancelled after at_source status it means that support team cancelled the order.
not_found No available Courier was found for the order.
not_response One or more available Couriers was found, but non of them has accepted the Order.
accept One of our Courier has accepted the Order.
at_source Courier has arrived at the Source of the Order.
pickup Courier picked up the package within 5 minutes (allowed pickup time)
reject Courier arrived at the source of the order, waited 5 minutes (allowed time to wait until picking up the package) then after 5 minutes Rejected the order.
at_destination Courier has been arrived at Destination of the Order.
drop Courier has delivered the package to the receiver of the Order. The signature and dropped[signatory] attributes might be filled by Courier if the Order.
returned Courier has returned back at the Source of the Order. This status is specific only for order that set the has_return attribute to true.
finish This status is not required you can finish the order and rate our courier. The rate and comment attributes might be filled by you while updating the Order to this status.

Webhooks

{
  "order": {
    "id": "68",
    "invoice_number": "N72XLP",
    "from_lat": "35.7528467389",
    "from_lng": "51.3520325418",
    "to_lat": "35.7603597142",
    "to_lng": "51.5101893553",
    "from_info": {
      "address": "\u0633\u06cc\u0645\u0627\u06cc \u0627\u06cc\u0631\u0627\u0646, \u06cc\u0627\u0632\u062f\u0647\u0645",
      "number": "54",
      "unit": "10",
      "description": "",
      "sender": {
        "firstname": "",
        "lastname": "",
        "phone": ""
      }
    },
    "to_info": {
      "address": "\u062a\u0647\u0631\u0627\u0646",
      "number": "37",
      "unit": "5",
      "description": "",
      "signatory": "Sample Signatory",
      "receiver": {
        "phone": "",
        "firstname": "",
        "lastname": "",
        "email": ""
      }
    },
    "status": "drop",
    "distance": "14295",
    "duration": "1764",
    "price": "24000",
    "credit": "0",
    "cashed": "0",
    "has_return": "1",
    "pay_at_dest": "0",
    "status_log": "1488392288,1488392341,1488392371,1488392402,1488392421",
    "signature": {
      "url": "\/uploads\/order\/68\/signature.jpg?var=1488392423"
    },
    "screenshot": {
      "url": "https:\/\/screenshots.alopeyk.com\/?size=640x330&maptype=roadmap&language=fa&markers=icon:https:\/\/alopeyk.com\/media\/home\/app\/courier-path\/marker-origin.png%7C35.7528467389,51.3520325418&markers=icon:https:\/\/alopeyk.com\/media\/home\/app\/courier-path\/marker-destination.png%7C35.7603597142,51.5101893553"
    },
    "progress": "83.3333333333",
    "order_token": "cf72d572468g17b1804510c929g74f600da4a5",
    "courier": {
      "phone": "09495275360",
      "firstname": "\u0645\u062d\u0645\u062f \u0631\u0636\u0627",
      "lastname": "\u0646\u0648\u0631\u0634\u06cc",
      "avatar": {
        "url": "\/uploads\/user\/75\/avatar.jpg?var=1488392423"
      },
      "last_position": {
        "lat": "35.7899425256",
        "lng": "51.4258848075",
      }
    },
    "tracking_url": "https://tracking.alopeyk.com/#/83832ac452714g2538246ae13c89g22463d865dd",
    "launched_at": "2017-03-01 21:47:38",
    "created_at": "2017-03-01 21:47:38",
    "updated_at": "2017-03-01 21:50:21"
  }
}

In order to send your API real-time updates, we recommend you to use our HTTP Webhooks. By providing us with an URL, we 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 there is any, as 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 Order ID
invoice_number Order’s Invoice Number (5 random chars).
from_lat Source Latitude.
from_lng Source Longitude.
to_lat Source Latitude.
to_lng Destination Longitude.
from_info Source Informations.
to_info Destination Informations.
status Status of the Order. See Order Statuses section for complete list of possible statuses.
distance Estimated distance between source and destination. (Powered by Google ETA)
duration Estimated duration for path between source and destination. (Based on Google Distance Matrix ETA)
price Price of the Order.
credit Payment type of the Order (Cash or Credit).
cashed Indicates that the payment type of Order is forced to be cash or not.
progress Current Progress of the Order as percent (between 0 and 100).
signature Signature of the Order. This attribute will be NULL until drop status.
screenshot Screenshot of the Order.
has_return Indicates that the Order has return option or not.
pay_at_dest Indicates that the Order must be paid at destination.
status_log Timestamps on which the status of the Order was updated, this attribute is a comma seperated attributes with a timestamp for each completed status for example if the order is in pickup status, you will have 4 timestamps seperated with commas for start / accept / at_source / pickup statuses.
courier Order’s Courier object, including phone, firstname, lastname. We have also included the latitude and longitude of the courier’s last position in this object.
order_token The unique token of the Order.
tracking_url The sharable tracking URL for the Order.
launched_at When the Order has been launched, this will be same as created_at attribute if the Order is not Scheduled.
updated_at The last time at which the Order has been updated.
created_at When the Order has been created.

Errors

Error Code Meaning
400 Bad Request – Your request sucks.
401 Unauthorized – Your Token is wrong.
403 Forbidden – You have not enough permissions to do this.
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access an API endpoint with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The kitten requested has been removed from our servers
429 Too Many Requests – You’re requesting too many kittens! Slow down!
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 its contain an error.

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