NAV Navbar
Partner Integrations
cURL

Overview

The base URL for all of the requests detailed in this documentation is:

  • Develop/Staging Environment
    https://apistg.ahamove.com

  • Production Environment
    https://api.ahamove.com

The core capabilities of the AhaMove app are available through the API:

AhaMove uses API_KEY to generate tokens to allow access to the API. You can register a new AhaMove API_KEY by send an email to our developer portal: minh@ahamove.com.

To check AhaMove API status, join this telegram chanel for more information https://t.me/aha_api_status

Quick Start

If you want to get start as quickly as possible, please follow these steps:

1. Register An User Account

You must have registered a partner account to use our APIs. Use api_key which we provided for you via email.

More detail

HTTP Request

curl -X GET \
  'https://apistg.ahamove.com/v1/partner/register_account?mobile=84908842280&name=Ahamove+Test+User&api_key=test_key' \  
  -H 'cache-control: no-cache'

GET https://apistg.ahamove.com/v1/partner/register_account?mobile=<phone_number>&name=Ahamove+Test+User&api_key=test_key

Response

JSON response example:

{ "token": "5d352c14eb44d753c5dcfc0b" }

Status-Code: 200 OK

2. Create An Order

After you had a token, you can create an order like the sample below.

More detail

HTTP Request

curl -X GET \
  'https://apistg.ahamove.com/v1/order/create?token=5d352c14eb44d753c5dcfc0b&order_time=0&path=[{"address":"Nhà Thờ Đức Bà, Vietnam"},{"address":"Chợ Bến Thành, Vietnam"}]&service_id=SGN-BIKE&&requests=[]' \  
  -H 'cache-control: no-cache'

GET https://apistg.ahamove.com/v1/order/create?token=<token>&order_time=0&path=[{"address":"Nhà Thờ Đức Bà, Vietnam"},{"address":"Chợ Bến Thành, Vietnam"}]&service_id=SGN-BIKE&&requests=[]

Response

JSON response example:

{
    "order_id": "1YQJVY",
    "status": "ASSIGNING",
    "shared_link": "https://cloudstg.ahamove.com/share-order/1YQJVY/84909055578",
    "order": {
        "_id": "1YQJVY",
        "currency": "VND",
        "user_main_account": 0,
        "user_bonus_account": 0,
        "total_pay": 32000,
        "distance": 5.68,
        "duration": 1464,
        "distance_fee": 32000,
        "request_fee": 0,
        "stop_fee": 0,
        "vat_fee": 0,
        "discount": 0,
        "path": [
            {
                "lat": 10.7692105,
                "lng": 106.6637935,
                "address": "725 Hẻm số 7 Thành Thái, Phường 14, Quận 10, Hồ Chí Minh, Việt Nam",
                "short_address": "Quận 10",
                "name": "nmbmb",
                "remarks": "call me"
            },
            {
                "lat": 10.7828887,
                "lng": 106.704898,
                "address": "Miss Ao Dai Building, 21 Nguyễn Trung Ngạn, Bến Nghé, Quận 1, Hồ Chí Minh, Vietnam",
                "name": "Bao"
            }
        ],
        "from_location": {
            "type": "Point",
            "coordinates": [
                106.6637935,
                10.7692105
            ]
        },
        "requests": [],
        "items": [],
        "total_fee": 32000,
        "app": "AhaMove",
        "service_id": "SGN-BIKE",
        "city_id": "SGN",
        "user_id": "84933939842",
        "user_name": "Test Create Order",
        "user_imei": null,
        "create_time": 1565577304.702157,
        "order_time": 1565577304.702157,
        "index": 2,
        "status": "ASSIGNING",
        "partner": "TESTPARTNER",
        "polylines": "sjv`A{w_jSsBcFtAsG`JqCuAaDlAef@f@e@Yw@~Kgi@p@MJw@mBcAgOeX_@cE`CsI_HyHe^wk@on@qk@eBnBgC{B",
        "online_pay": 0,
        "notify_package_return": true,
        "uniform_user_feedback": 2,
        "pending_period": 100,
        "parent_user_id": "84909055578",
        "stoppoint_price": 0,
        "special_request_price": 0,
        "vat": 0,
        "distance_price": 32000,
        "voucher_discount": 0,
        "subtotal_price": 32000,
        "total_price": 32000
    }
}

Status-Code: 200 OK

Account APIs

Register Account

HTTP Request

curl -X GET \
  'https://apistg.ahamove.com/v1/partner/register_account?mobile=84908842280&name=Ahamove+Test+Create+User&api_key=test_key&address=7/28 Thành Thái, Quận 10, TP. HCM' \  
  -H 'cache-control: no-cache'

GET https://apistg.ahamove.com/v1/partner/register_account

Query Parameters

Parameter Type Required Description
api_key String Yes The API_KEY of your application which received when you send an email to our developer portal.
mobile String Yes Your phone number used to register account ID.
name String Yes Your account name.
address String Yes Your home address (Optional if account already existed).
lat String Yes Latitude of home address (Optional if account already existed).
lng String Yes Longitude of home address (Optional if account already existed).
email String No Your email address.
parent_id String No Parent Account ID.
country_code String No Country code, used for formatting the mobile number (default VN).

Response

JSON response example:

{ "token": "5d352c14eb44d753c5dcfc0b" }

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found api_key not found, parent_id not found.
401 Unauthorized Update existing account not belong to this partner.
409 Conflict Email existed.
403 Forbidden Account is deactivated.
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Add Child Account

Add child account to a parent account, the parent account needs to be enabled by the “partner” field. A SMS code will be sent to child account for verification

HTTP Request

curl -X GET \
  'https://apistg.ahamove.com/v1/partner/add_child_account?token=5d352c14eb44d753c5dcfc0b&child_id=84979003147' \  
  -H 'cache-control: no-cache'

GET https://apistg.ahamove.com/v1/partner/add_child_account

Query Parameters

Parameter Type Required Description
token String Yes Parent token.
child_id String Yes Child Account ID.

Response

JSON response example:

  {}

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found Token not found, child_id not found.
401 Unauthorized Parent account doesn’t have the “partner” field or child account belongs to another partner.
409 Conflict Parent account existed, Sub-child accounts existed (The child account already has a parent or is already a parent of other accounts).
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Activate Child Account

Activate child account to a parent account

HTTP Request

curl -X GET \
  'https://apistg.ahamove.com/v1/partner/activate_child_account?token=5d352c14eb44d753c5dcfc0b&child_id=84979003147&activation_code=1234' \  
  -H 'cache-control: no-cache'

GET https://apistg.ahamove.com/v1/partner/activate_child_account

Query Parameters

Parameter Type Required Description
token String Yes Parent token.
child_id String Yes Child Account ID.
activation_code String Yes Activation code was received when adding a child account to parent account.

Response

JSON response example:

{
  "_id": 84979003147,
  "name": "Minh Pham",
  ....
}

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found Token not found, child_id not found.
401 Unauthorized Parent account doesn’t have the “partner” field or child account belongs to another partner.
409 Conflict Parent existed, Sub-child accounts existed (The child account already has a parent or is already a parent of other accounts).
406 Not Acceptable Activation code not valid.
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Remove Child Account

Remove child account out of parent account, the parent account needs to be enabled by the “partner” field

HTTP Request

curl -X GET \
  'https://apistg.ahamove.com/v1/partner/remove_child_account?token=5d352c14eb44d753c5dcfc0b&child_id=84979003147' \  
  -H 'cache-control: no-cache'

GET https://apistg.ahamove.com/v1/partner/remove_child_account

Query Parameters

Parameter Type Required Description
token String Yes Parent token.
child_id String Yes Child Account ID.

Response

JSON response example:

{ }

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found Token not found, child_id not found.
401 Unauthorized Parent account doesn’t have the “partner” field or child account belongs to another partner.
402 Not allowed Child main balance < 0 or child has ongoing orders.
406 Not Acceptable child_id not valid (child_id not found in parent account).
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Get Child Account List

Returns a list of child accounts of a parent account with parent token

HTTP Request

curl -X GET \
  'https://apistg.ahamove.com/v1/partner/get_child_list?token=5d352c14eb44d753c5dcfc0b' \  
  -H 'cache-control: no-cache'

GET https://apistg.ahamove.com/v1/partner/get_child_list

Query Parameters

Parameter Type Required Description
token String Yes Parent token.

Response

JSON response example:

[
  {
    "_id": "84819815842",
    "name": "store test test test",
    "partner": "test_key",
    "email": null,
    "referral_code": "0819815842",
    "country_code": "VN",
    "currency": "VND",
    "account_status": "ACTIVATED",
    "create_time": 1551155326.708945,
    "parent_id": "84979003147",
    "home": {
      "address": "4 Nguyen Dinh Chieu,Da Kao,Quan 1,TPHCM",
      "lat": 10.7918246,
      "lng": 106.7022344
    },
    "city_id": [
      "SGN"
    ]
  }
]

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found Token not found.
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Update User Profile

Update a user profile

HTTP Request

curl -v -X POST \
  'https://apistg.ahamove.com/v1/user/update_profile' \  
  -H 'cache-control: no-cache'
  -d '{
        "token": "5e9874be2901bb000d34b5f3",
        "name": "John Doe",
        "email": "johndoe@gmail.com",
        "user_type": "SMEs",
        "categories": [
            {
                "code": "FOOD",
                "child_code": [
                    "VIETNAMESE SPECIALTIES",
                    "ICE-CREAM",
                    "PHO & NOODLES"
                ]
            },
            {
                "code": "DRINK",
                "child_code": [
                    "MILK TEA",
                    "SMOOTHIE & JUICE",
                    "BEVERAGE"
                ]
            }
        ]
 }'

POST https://apistg.ahamove.com/v1/user/update_profile

Query Parameters

Parameter Type Required Description
token String Yes Token.
name String No User Name.
email String No Email.
user_type String No User Type (Individual/SMEs/Corporation).
categories Array No Category.

Response

JSON response example:

  {}

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found Token not found.
409 Conflict Email existed.
406 Not Acceptable Email not valid.
400 Bad Request Invalid user type and categories.
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Order APIs

Data Model

JSON example:

{
    # Status, Service, Request
    "_id" : "QMB0HO",
    "status" : "CANCELLED",
    "service_id" : "SGN-TRICYCLE", # Service ID
    "city_id" : "SGN", # City ID

    # List of special requests
    "requests" : [
        {
            "_id":"SGN-TRUCK-500-CART",
            "num":2,
            "price": 100000 # Final request price = 50000 x 2
        },
        {
            "_id":"SGN-TRUCK-500-BOCXEP",
            "price": 50000,
        },
        {
            "_id":"SGN-TRUCK-500-COD",
            "price": 0,
            "value": 300000
        },
        {
            "_id":"SGN-COFFEEHOUSE-COMBO-1",
            "num": 2,
            "price": 0, # Request fee
            "item_price": 980000 # Final item price = 49000 x 2
        }
    ],

    # User ID & Supplier ID
    "user_id" : "84972709963", # User who created this order
    "user_name" : "Thao Vy", # User name
    "supplier_id" : "84909561477", # Supplier who accepted this order
    "supplier_name" : "Hieu Nguyen", # Supplier name

    # Partner
    "partner": "foodbook", # If this order is created by 3rd-party partners

    # Time
    "order_time" : 1426297774, # Pick-up time
    "create_time" : 1426297174.649361, # Order create time
    "accept_time" : 1426298634.189912, # Order accept time
    "accept_lat": 10.7890462,
    "accept_lng": 106.7763078,
    "accept_distance": 1.2, # Distance from accepted location to pick up point
    "accept_duration": 150, # Time from accepted location to pick up point

    "cancel_time" : 1426671164.374609, # Order cancel time
    "cancel_comment" : "Lich chuyen nha bi hoan", # Cancelled reason by user or supplier
    "cancel_by_user" : False, # True if this order is cancelled by user, otherwise False
    # Others: complete_time, complete_lat, complete_lng, accept_lat, accept_lng, fail_time, fail_lat, fail_lng, fail_comment

    # Payment
    "currency" : "VND",
    "stop_fee" : 0,
    "request_fee" : 0,
    "distance" : 5.597,
    "distance_fee" : 142358,
    "promo_code" : "AHAMOVE",
    "discount" : 0,
    "total_fee" : 142358, # Total fee = Distance Fee + Request Fee + Stop Fee - Discount
    "payment_method": "BALANCE" # User pay by Ahamove balance (Available methods: CASH | BALANCE)

    # Use credit from user account if available
    "user_bonus_account" : 0,
    "user_main_account" : 0,
    "total_pay" : 142358, # Total pay = Total fee - User Main account - User Bonus account

    # Supplier commission = Service commission = Supplier Main account + Supplier Bonus account
    "supplier_main_account" : 0,
    "supplier_bonus_account" : 14235.8,

    # These fields applied for food orders
    "partner_fee" : 20000, # Partner total fee = Partner Distance Fee + Request Fee + Stop Fee - Discount
    "partner_distance_fee" : 10000,
    "partner_subsidy":  20000, # partner_subsidy = total_fee - partner_fee
    "partner_discount": 10000, # discount = partner_discount + partner_subsidy
    "partner_pay": 90000, # Total partner pay in cash, partner_pay = total_pay + item_fee - item_discount + item_vat_fee
    "online_pay": 0, # Total pay via online channels

    # Rating
    "rating_by_user": 4,
    "comment_by_user": "Good",
    "rating_by_supplier": 5,
    "comment_by_supplier": "Great customer",
    "rating_by_receiver": 4,
    "comment_by_receiver": "Good driver",
    "store_rating_by_user": 4, # For food orders
    "store_comment_by_user": "Delicious food", # For food orders

    # Path, at least 2 locations, 1 From and >= 1 To
    "path" : [
        {
            "lat" : 10.7890462,
            "lng" : 106.7763078,
            "address" : "Số 47, Bình Trưng Đông, Quận 2, Hồ Chí Minh, Vietnam",
        },
        {
            "lat" : 10.76403580333166,
            "lng" : 106.7558794096112,
            "address" : "Vũ Phương Đề, Thạnh Mỹ Lợi, Quận 2, Hồ Chí Minh, Vietnam",

            "mobile": "0908842285",
            "name": "Ngon",
            "cod": 500000,
            "remarks": "Call me when arrive",
            "require_pod": True, # If true, supplier will be required proof of delivery before complete the transaction
            "require_verification": True, # If true, a verification code will be sent to the receiver, then the supplier will need to enter this code to complete the transaction

            "rating_by_receiver": 4,
            "comment_by_receiver": "Good",

            "complete_time": 1426671164,
            "complete_lat": 10.7890462,
            "complete_lng": 106.7763078,
            "complete_comment": "Nice receiver",
            "image_url": "http://i.imgur.com/lchC2xz.jpg", # Image to show that the supplier has already completed the order, uploaded by the supplier
            "pod_info" : "024792155", # Proof of delivery information that supplier has collected, can be recipient's ID number or image URL
            "status": "COMPLETED"
        },
        {
            "lat" : 10.7640412,
            "lng" : 106.755910,
            "address" : "Nha tho Duc Ba",

            "mobile": "0908842285",
            "name": "Ngon",
            "cod": 500000,
            "remarks": "Call me when arrive",

            "fail_time": 1426671164,
            "fail_comment": "User does not show",
            "fail_lat": 10.7890462,
            "fail_lng": 106.7763078,
            "status": "FAILED",

            # Note from supplier, to reschedule time and address for failed delivery
            "redelivery_note":
                {
                    "from_time" : NumberInt(1532109600), # Redeliver after this time
                    "to_time" : NumberInt(1532111400), # Redeliver before this time
                    "address" : "21 Nguyễn Trung Ngạn, Bến Nghé, Quận 1, Hồ Chí Minh, Vietnam", # Redelivery address
                    "lat" : 10.782938,
                    "lng" : 106.704899
                }
        }
    ],

    # Others
    "remarks": "Den noi goi dien cho toi", # Note to supplier
    "remind": True, # If this is advance booking and the system already reminds users
    "assigned_by": "84908842285", # If this order is assigned by a user or "auto" if by the system
    "index": 1, # 0 if first order request from the user, 1 for second...

    # For internal Geo index only
    "from_location" : {
        "type" : "Point",
        "coordinates" : [
            106.7763078,
            10.7890462
        ]
    }
}
Parameter Type Description
id String Order ID.
status String Order status more detail.
service_id String Service ID.
city_id String City ID.
user_id String User ID who created this order.
user_name String User name who created this order.
partner String Partner ID.
supplier_id String Supplier who accepted this order.
supplier_name String Supplier name.
path Object Pickup and drop-offs information
--------- ---------- ----------
create_time Number Time when order was created, in epoch timestamp format.
order_time Number Time user want supplier to pick up his package, in epoch timestamp format.
accept_time Number Time when a supplier accept an order, in epoch timestamp format
board_time Number Time when a supplier come to user place, in epoch timestamp format.
pickup_time Number Time when a supplier pick up user package successfully, in epoch timestamp format.
cancel_time Number Time when an order was cancelled, in epoch timestamp format.
complete_time Number Time when an order was completed, in epoch timestamp format.
--------- ---------- ----------
currency String Currency (ISO 4217 currency code)
promo_code String Promotion code to be applied
payment_method String Method which user chooses to pay for this order (Available methods: CASH
stop_fee Number Stop fee for multiple drop-offs (Will be removed after December 1st, 2019)
request_fee Number Extra fee for adding special request to the order (Will be removed after December 1st, 2019)
distance_fee Number Service fee calculated based on distance (Will be removed after December 1st, 2019)
discount Number Discount (Will be removed after December 1st, 2019)
total_fee Number Total fee (Total fee = Distance Fee + Request Fee + Stop Fee - Discount) (Will be removed after December 1st, 2019)
user_bonus_account Number The amount of credit which is deducted fron user bonus account if bonus account have enough credit
user_main_account Number The amount of credit which is deducted fron user main account if main account have enough credit
total_pay Number The amount of CASH that user has to pay for this order (Total pay = Total fee - User Main account - User Bonus account)
--------- ---------- ----------
distance_price Number Service fee calculated based on distance (alternaltive for distance_fee)
special_request_price Number Extra fee for adding special request to the order (alternaltive for request_fee)
stoppoint_price Number Stop fee for multiple drop-offs (alternaltive for stop_fee)
voucher_discount Number Discount (alternaltive for discount)
subtotal_price Number Sum of distance price, special_request_price,stoppoint_price (alternaltive for total_fee)
total_price Number Final price, equals subtotal_price - voucher_discount

Path

Representing From path[0] and multiple Tos path[x], x > 0

Parameter Type Description
address String Address of the location.
lat Number Latitude of the location.
lng Number Longitude of the location.
name String Recipient's name. Optional if is path[0].
mobile String Recipient's mobile number. Optional if is path[0].
tracking_number String Tracking number for the package (Partner's order id).
remarks String Note to supplier, for multiple delivery points.
cod Number COD amount (Cash on delivery), for multiple delivery points.
status String Delivery Status (detail)
building String Building name for delivery to door
apt_number String Apartment, Suite or Floor number for delivery to door

Create Order

curl --request POST \
  --url https://apistg.ahamove.com/v1/order/create \
  --header 'Accept: */*' \
  --header 'Cache-Control: no-cache' \  
  --data 'token=5d352c14eb44d753c5dcfc0b&order_time=0&path=[{"lat":10.7692105,"lng":106.6637935,"address":"725 Hẻm số 7 Thành Thái, Phường 14, Quận 10, Hồ Chí Minh, Việt Nam","short_address":"Quận 10","name":"nmbmb","remarks":"call me"},{"lat":10.7828887,"lng":106.704898,"address":"Miss Ao Dai Building, 21 Nguyễn Trung Ngạn, Bến Nghé, Quận 1, Hồ Chí Minh, Vietnam","name":"Bao"}]&service_id=SGN-BIKE&requests=[]'

Create a new order by user (support both GET/POST method)

HTTP Request

POST https://apistg.ahamove.com/v1/order/create

or

GET https://apistg.ahamove.com/v1/order/create

Parameters

# Parameters
{
    "order_time": 0,
    "path": [
      {
        "lat": 10.7692105,
        "lng": 106.6637935,
        "address": "725 Hẻm số 7 Thành Thái, Phường 14, Quận 10, Hồ Chí Minh, Việt Nam",
        "short_address": "Quận 10",
        "name": "nmbmb",
        "remarks": "call me"
      },
      {
        "lat": 10.7828887,
        "lng": 106.704898,
        "address": "Miss Ao Dai Building, 21 Nguyễn Trung Ngạn, Bến Nghé, Quận 1, Hồ Chí Minh, Vietnam",
        "name": "Bao"
      }
    ],
    "service_id": "SGN-BIKE",
    "requests": [],
    "images": [],
    "promo_code": "KHUYENMAI",
    "remarks": "Call me when arrived",
    "payment_method": "CASH",
    "items": [
      {
        "_id": "TS",
        "num": 2,
        "name": "Sua tuoi",
        "price": 15000
      },
      {
        "_id": "ST",
        "num": 2,
        "name": "Sinh to lua mach",
        "price": 30000
      }
    ]
}
Parameter Type Required Description
token String Yes The user Token.
order_time Number (Unix timestamp) Yes The pickup time. Set 0 to pickup ASAP.
path String Yes At least 2 pairs (described in more detail below).
service_id String Yes AhaMove Service ID (SGN-BIKE, SGN-POOL, etc.).
requests Array Yes JSONArray representing Special Requests.
payment_method String Yes Payment method chosen by user (BALANCE or CASH)- Require on production after December 1st, 2019.
images Array No JSONArray representing image urls.
promo_code String No Promo code to discount shipping fee.
remarks String No Remarks.
idle_until Number (Unix timestamp) Yes The broadcast time. Set idle_until=order_time if order_time > 0. Optional if order_time is 0.
items Array No JSONArray representing items (for Food Partners)
type String No Order type, for eg: warehouse, etc … Treat as normal flow incase type is not specified
need_optimize_route Boolean No In case, if partner need AhaMove to optimize route (1 pickup, > 2 drop off points)

Path

Representing From path[0] and multiple Tos path[x], x > 0

Parameter Type Required Description
address String Yes Address of the location.
lat Number Yes Latitude of the location.
lng Number Yes Longitude of the location.
name String Yes Recipient's name. Optional if is path[0].
mobile String Yes Recipient's mobile number. Optional if is path[0].
tracking_number String No Tracking number for the package (Partner's order id).
remarks String No Note to supplier, for multiple delivery points.
cod Number No COD amount (Cash on delivery), for multiple delivery points.
require_pod Boolean No If true, supplier will be required proof of delivery before complete the transaction
building String No Building name for delivery to door
apt_number String No Apartment, Suite or Floor number for delivery to door
sender_name String No Sender's name, for multiple delivery points
sender_mobile String No Sender's mobile, for multiple delivery points

Response

JSON response example:

{
    "order_id": "USAGND",
    "status": "ASSIGNING",
    "shared_link": "https://cloudstg.ahamove.com/share-order/USAGND/84909055578",
    "order": {
        "_id": "USAGND",
        "currency": "VND",
        "user_main_account": 0,
        "user_bonus_account": 0,
        "total_pay": 23000,
        "distance": 1.02,
        "duration": 268,
        "distance_fee": 23000,
        "request_fee": 0,
        "stop_fee": 0,
        "vat_fee": 0,
        "discount": 0,
        "path": [
            {
                "address": "Nhà Thờ Đức Bà, Vietnam",
                "lat": 10.7797855,
                "lng": 106.6990189
            },
            {
                "address": "Chợ Bến Thành, Vietnam",
                "lat": 10.7725451,
                "lng": 106.6980413
            }
        ],
        "from_location": {
            "type": "Point",
            "coordinates": [
                106.6990189,
                10.7797855
            ]
        },
        "requests": [],
        "items": [],
        "total_fee": 23000,
        "app": "AhaMove",
        "service_id": "SGN-BIKE",
        "city_id": "SGN",
        "user_id": "84909055578",
        "user_name": "TEST CREATE AN ORDER",
        "user_imei": null,
        "create_time": 1565577713.2757928,
        "order_time": 1565577713.2757928,
        "index": 12,
        "status": "ASSIGNING",
        "partner": "TESTPARTNER",
        "polylines": "ukx`A}rfjS~CuDhHnGlBnA|DoEdFcB|BhBxBtDzBmA",
        "online_pay": 0,
        "notify_package_return": true,
        "uniform_user_feedback": 2,
        "pending_period": 100,
        "stoppoint_price": 0,
        "special_request_price": 0,
        "vat": 0,
        "distance_price": 23000,
        "voucher_discount": 0,
        "subtotal_price": 23000,
        "total_price": 23000
    }
}

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found - Token not found
- Path not found
- Service not found
406 Not Acceptable - Booking time not valid
- Address not valid
- Request not valid
- Distance not valid
- Invalid pickup area
- Invalid delivery area
- Concurrent order not allowed (If partner not in token)
- Large COD not allowed for first time user
- Post paid not set for partner
- Not supported payment method
- Not enough credit
- User’s phone number associated with
- Token has been used for a partner
- Child order status not valid (When creating parent order)
- Parent order existed for #ABCXYZ (When creating a parent order but child orders already had a parent)
- Idle until not valid (When client sent idle_until < current_time)
- COD is not valid ( When total COD exceeds the maximum value which was configured in service)
- Number of stop points are not valid
408 Request timeout Google Distance API does not return results in 10 seconds.
409 Conflict - New order not allow (Not allow 2 consecutive orders in 1 minute)
- Tracking number duplicated (Not allow to create duplicated tracking number within 60s)
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Estimate Order Fee

# Example Request
curl --request POST \
  --url https://apistg.ahamove.com/v1/order/estimated_fee \
  --header 'Accept: */*' \
  --header 'Cache-Control: no-cache' \  
  --data 'token=5d4bcb47ed4f1f0b3b5e9b20&order_time=0&path=[{"lat":10.7692105,"lng":106.6637935,"address":"725 Hẻm số 7 Thành Thái, Phường 14, Quận 10, Hồ Chí Minh, Việt Nam","short_address":"Quận 10","name":"nmbmb","remarks":"call me"},{"lat":10.7828887,"lng":106.704898,"address":"Miss Ao Dai Building, 21 Nguyễn Trung Ngạn, Bến Nghé, Quận 1, Hồ Chí Minh, Vietnam","name":"Bao"}]&service_id=SGN-BIKE&requests=[]'

This api is used to estimate order fee (support both GET/POST method)

HTTP Request

POST https://apistg.ahamove.com/v1/order/estimated_fee

or

GET https://apistg.ahamove.com/v1/order/estimated_fee

Parameters

The same as order/create API

Response

JSON response example:

{
  "distance": 1.13,
  "duration": 290,
  "requests": [],
  "user_main_account": 0,
  "user_bonus_account": 0,
  "currency": "VND",
  "total_pay": 32000,
  "polyline_points": "sjv`A{w_jSsBcFtAsG`JqCuAaDlAef@f@e@Yw@~Kgi@p@MJw@mBcAgOeX_@cE`CsI_HyHe^wk@on@qk@eBnBgC{B",
  "polylines": "sjv`A{w_jSsBcFtAsG`JqCuAaDlAef@f@e@Yw@~Kgi@p@MJw@mBcAgOeX_@cE`CsI_HyHe^wk@on@qk@eBnBgC{B",
  "is_postpaid": false,
  "is_child_account": false,
  "total_balance": 0,
  "online_pay": 0,
  "distance_fee": 32000,
  "request_fee": 0,
  "stop_fee": 0,
  "vat_fee": 0,
  "discount": 0,
  "total_fee": 32000,
  "stoppoint_price": 0,
  "special_request_price": 0,
  "vat": 0,
  "distance_price": 32000,
  "voucher_discount": 0,
  "subtotal_price": 32000,
  "total_price": 32000,
  "surcharge": 1.1,
  "surge_rate": 1.1, # It means that price increase 110% comparing to the original
  "booking_time_error": "Booking time not valid" #If booking time is not in opening hours period,
  "payment_error_message": "Not enough credit" #If user does not have enough credit in balance
}

Status-Code: 200 OK

Field Description
distance Distance
duration Estimated lead time
requests Special requests
currency Currency
polylines You can use the polyline to draw lines on a map in Google Maps.
booking_time_error "Booking time not valid" #If booking time is not in opening hours period.
payment_error_message "Not enough credit" #If user does not have enough credit in balance.
distance_fee Distance fee (Will be removed after December 1st, 2019)
request_fee Request fee (Will be removed after December 1st, 2019)
stop_fee Stop fee, for multiple dropoff locations (Will be removed after December 1st, 2019)
vat_fee VAT (Will be removed after December 1st, 2019)
discount Discount (Will be removed after December 1st, 2019)
total_fee Total fee (Will be removed after December 1st, 2019)
surcharge Surge pricing level, only returned if surcharge > 1. (Will be removed after December 1st, 2019)
distance_price Distance fee, alternaltive for distance_fee
special_request_price Request fee, alternaltive for request_fee
stoppoint_price Stop fee, alternaltive for stop_fee
vat VAT, alternaltive for vat_fee
voucher_discount Discount, alternaltive for discount
subtotal_price Total fee, alternaltive for total_fee
total_price Final price, equals subtotal_price - voucher_discount
surge_rate Sometimes, service price may increase due to the demand increasing unexpectedly. This rate will be returned if it is greater than 1, alternaltive for surcharge
total_pay Total pay by cash
online_pay Amount of money that user pay for ahamove through a 3rd party payment service (For example MOMO)

Errors

The same as order/create API

Estimated Order Fee with many services at once

# Example Request
curl -X POST \
  https://apistg.ahamove.com/v2/order/estimated_fee \
  -H 'Content-Type: application/json' \
  -d '{"token":"5d4bcb47ed4f1f0b3b5e9b20","order_time": 0, "path": [{"lat":10.7692105, "lng":106.6637935, "address":"725 Hẻm số 7 Thành Thái, Phường 14, Quận 10, Hồ Chí Minh, Việt Nam", "short_address":"Quận 10", "name":"nmbmb", "remarks":"call me"}, {"lat":10.7828887, "lng":106.704898, "address":"Miss Ao Dai Building, 21 Nguyễn Trung Ngạn, Bến Nghé, Quận 1, Hồ Chí Minh, Vietnam", "name":"Bao"}], "services":[{"_id":"SGN-BIKE","requests":[{"_id":"SGN-BIKE-ROUND-TRIP","price":18400}]}, {"_id": "SGN-TRICYCLE"}], "payment_method": "CASH"}'

Return estimated fee for trip that has the same pick up and drop off points within many services

HTTP Request

POST https://apistg.ahamove.com/v2/order/estimated_fee

Response

Success response example:

Status-Code: 200 OK

[
  {
      "distance": 11.72,
      "duration": 3220,
      "requests": [],
      "user_main_account": 0,
      "user_bonus_account": 0,
      "currency": "VND",
      "total_pay": 80000,
      "polyline_points": "sjv`A{w_jS\\hBwKzDdHtWwCh@{Cda@pKbABxAxV`a@cIlXKxCh@]lTkaAmFsFfGsDiC}FbJoFwDoI|Ag@iL_w@i@HqAuHoCJeEk\\cB{B~Myk@qB}@cNgVc@sFsJaJfDoCkAsCfAk@q]_k@on@qk@eBnB_CsB",
      "polylines": "sjv`A{w_jS\\hBwKzDdHtWwCh@{Cda@pKbABxAxV`a@cIlXKxCh@]lTkaAmFsFfGsDiC}FbJoFwDoI|Ag@iL_w@i@HqAuHoCJeEk\\cB{B~Myk@qB}@cNgVc@sFsJaJfDoCkAsCfAk@q]_k@on@qk@eBnB_CsB",
      "total_balance": 0,
      "is_postpaid": false,
      "is_child_account": false,
      "online_pay": 0,
      "payment_method": "CASH",
      "distance_fee": 75000,
      "request_fee": 0,
      "stop_fee": 5000,
      "vat_fee": 0,
      "discount": 0,
      "total_fee": 80000,
      "surcharge": 1.21,
      "stoppoint_price": 5000,
      "special_request_price": 0,
      "vat": 0,
      "distance_price": 75000,
      "voucher_discount": 0,
      "subtotal_price": 80000,
      "total_price": 80000,
      "surge_rate": 1.21,
      "_id": "SGN-BIKE"
  },
  {
      "distance": 11.72,
      "duration": 3220,
      "requests": [],
      "user_main_account": 0,
      "user_bonus_account": 0,
      "currency": "VND",
      "total_pay": 307000,
      "polyline_points": "sjv`A{w_jS\\hBwKzDdHtWwCh@{Cda@pKbABxAxV`a@cIlXKxCh@]lTkaAmFsFfGsDiC}FbJoFwDoI|Ag@iL_w@i@HqAuHoCJeEk\\cB{B~Myk@qB}@cNgVc@sFsJaJfDoCkAsCfAk@q]_k@on@qk@eBnB_CsB",
      "polylines": "sjv`A{w_jS\\hBwKzDdHtWwCh@{Cda@pKbABxAxV`a@cIlXKxCh@]lTkaAmFsFfGsDiC}FbJoFwDoI|Ag@iL_w@i@HqAuHoCJeEk\\cB{B~Myk@qB}@cNgVc@sFsJaJfDoCkAsCfAk@q]_k@on@qk@eBnB_CsB",
      "total_balance": 0,
      "is_postpaid": false,
      "is_child_account": false,
      "online_pay": 0,
      "payment_method": "CASH",
      "distance_fee": 297000,
      "request_fee": 0,
      "stop_fee": 10000,
      "vat_fee": 0,
      "discount": 0,
      "total_fee": 307000,
      "stoppoint_price": 10000,
      "special_request_price": 0,
      "vat": 0,
      "distance_price": 297000,
      "voucher_discount": 0,
      "subtotal_price": 307000,
      "total_price": 307000,
      "_id": "SGN-TRICYCLE"
  }
]

Errors

Return list detail error with status_code, title, description by each service_id.

Error response example:

Status-Code: 200 OK

[
    {
        "_id": "SGN-TRICYCLE-NOT-EXIST",
        "title": "Service not found",
        "description": "Service SGN-TRICYCLE-NOT-EXIST not found"
    },
    {
        "distance": 11.72,
        "duration": 3220,
        "user_main_account": 0,
        "user_bonus_account": 0,
        "currency": "VND",
        "total_pay": 80000,
        "polyline_points": "sjv`A{w_jS\\hBwKzDdHtWwCh@{Cda@pKbABxAxV`a@cIlXKxCh@]lTkaAmFsFfGsDiC}FbJoFwDoI|Ag@iL_w@i@HqAuHoCJeEk\\cB{B~Myk@qB}@cNgVc@sFsJaJfDoCkAsCfAk@q]_k@on@qk@eBnB_CsB",
        "polylines": "sjv`A{w_jS\\hBwKzDdHtWwCh@{Cda@pKbABxAxV`a@cIlXKxCh@]lTkaAmFsFfGsDiC}FbJoFwDoI|Ag@iL_w@i@HqAuHoCJeEk\\cB{B~Myk@qB}@cNgVc@sFsJaJfDoCkAsCfAk@q]_k@on@qk@eBnB_CsB",
        "total_balance": 0,
        "is_postpaid": false,
        "is_child_account": false,
        "online_pay": 0,
        "payment_method": "CASH",
        "requests": [],
        "distance_fee": 75000,
        "request_fee": 0,
        "stop_fee": 5000,
        "vat_fee": 0,
        "discount": 0,
        "total_fee": 80000,
        "surcharge": 1.21,
        "stoppoint_price": 5000,
        "special_request_price": 0,
        "vat": 0,
        "distance_price": 75000,
        "voucher_discount": 0,
        "subtotal_price": 80000,
        "total_price": 80000,
        "surge_rate": 1.21,
        "_id": "SGN-BIKE"
    }
]

Cancel Order

curl -X GET \
  'http://apistg.ahamove.com/v1/order/cancel?token=5d352c14eb44d753c5dcfc0b&order_id=ABCDEF&comment=Supplier+does+not+show+up' \  
  -H 'cache-control: no-cache'

This API is used to cancel an order

HTTP Request

GET https://apistg.ahamove.com/v1/order/cancel

Query Parameters

Parameter Type Required Description
token String Yes The user Token.
order_id String Yes The order ID.
comment String Yes if order in ACCEPTED status The cancel reason.

Response

JSON response example:

{}

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found - Token not found
- Order not found
402 Not allowed Not authorized.
406 Not Acceptable Order not in valid status.
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Get Order List

curl -X GET \
  'http://apistg.ahamove.com/v1/order/list?token=5d352c14eb44d753c5dcfc0b' \  
  -H 'cache-control: no-cache'

This API is used to get a list of orders for a user. The returned list is sorted in descending order by order_time

HTTP Request

GET https://apistg.ahamove.com/v1/order/list

Query Parameters

Parameter Type Required Description
token String Yes The user Token.
status String No Filter by order status
count Number No Number of elements returned, default 20
offset Number No Offset, default 0
from_time Number No Filter by order_time
to_time Number No Filter by order_time
child_ids Array No Limit to a subset of child ids, for partner account
fields String No Set to return only these fields
total Boolean No Return total count, default False

Response

JSON response example:

[
  {
    "_id": "ABCDEF",
    ... # order detail
  },
  ...
]

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found Token not found
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Get Order Detail

curl -X GET \
  'http://apistg.ahamove.com/v1/order/detail?token=5d352c14eb44d753c5dcfc0b&order_id=ABCDEF' \  
  -H 'cache-control: no-cache'

This API is used to get detail information about an order

HTTP Request

GET https://apistg.ahamove.com/v1/order/detail

Query Parameters

Parameter Type Required Description
token String Yes The user Token.
order_id String No order id

Response

JSON response example:

{
  "_id": "ABCDEF",
  ...# order detail
}

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found Token not found
401 Unauthorized Unauthorized
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Get City Detail

curl -X GET \
  'https://apistg.ahamove.com/v1/order/city_detail?city_id=SGN' \  
  -H 'cache-control: no-cache'

This API is used to get detail information about a city

HTTP Request

GET https://apistg.ahamove.com/v1/order/city_detail?city_id=<city_id>

or

GET https://apistg.ahamove.com/v1/order/city_detail?lat=<lat>&lng=<lng>

Query Parameters

Parameter Type Required Description
city_id String Yes City ID
lat Number No Latitude
lng Number No Longitude

Response

JSON response example:

{
    "_id" : "SGN",
    "name" : "Ho Chi Minh City",
    "name_vi_vn" : "TP Hồ Chí Minh",
    "country_id" : "VN",
    "location" : {
        "type" : "Point",
        "coordinates" : [
            106.6943626,
            10.768451
        ]
    }
}

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found City not found
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Get List Of Service

curl -X GET \
  'https://apistg.ahamove.com/v1/order/service_types?lat=10.768451&lng=106.6943626' \  
  -H 'cache-control: no-cache'

This API is used to get list of services that are available at the current location

HTTP Request

GET https://apistg.ahamove.com/v1/order/service_types

or

GET https://apistg.ahamove.com/v1/order/service_types

Query Parameters

Parameter Type Required Description
lat String Yes Latitude, Optional if city_id
lng String Yes Longitude, Optional if city_id
city_id String No City Id

Response

JSON response example:

[
    {
        _id: "SGN-TRICYCLE",
        order: 2,
        name: "Xe ba gac (1.8 x 1.3m)",
        name_vi_vn: "Xe ba gac (1.8 x 1.3m)",
        currency: "VND",
        city_id: "SGN",
        icon_url: "http://apistg.ahamove.com/images/tricycle.png",
        parent_id: "",
        distance_fee: "120000 if x <= 4 else 120000 + (x - 4) * 14000",
        stop_fee: 10000,

        # List of special requests
        requests: [
            {
                enable: true,
                name_vi_vn: "Boc xep",
                name: "Boc xep",
                icon_url: "http://apistg.ahamove.com/images/loading.png",
                price: 65000,
                service_id: "SGN-TRICYCLE",
                _id: "SGN-TRICYCLE-BOCXEP",
                type: "BOOLEAN",
                order: 2,
                description: "Boc xep tai cac diem xe co the dung do"
            }
        ],
    }
]

Status-Code: 200 OK

Errors

Code Text Description
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.
curl -X GET \
  'https://apistg.ahamove.com/v1/order/shared_link?token=5d352c14eb44d753c5dcfc0b&order_id=ABCDEF' \  
  -H 'cache-control: no-cache'

This API is used to get the shared link for order tracking

HTTP Request

GET https://apistg.ahamove.com/v1/order/shared_link

Query Parameters

Parameter Type Required Description
token String Yes User Token
order_id String Yes Order Id

Response

JSON response example:

{
  "shared_link": "https://cloudstg.ahamove.com/share-order/ABCDEF/84979003147"
}

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found - Token not found
- Order not found
401 Unauthorized Unauthorized
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Rate A Supplier

curl -X GET \
  'https://apistg.ahamove.com/v1/order/rate_supplier?token=5d352c14eb44d753c5dcfc0b&order_id=ABCDEF&rating=5&comment=Good+guy' \  
  -H 'cache-control: no-cache'

This API is used to rate a supplier after complete an order

HTTP Request

GET https://apistg.ahamove.com/v1/order/rate_supplier

Query Parameters

Parameter Type Required Description
token String Yes User Token
order_id String Yes Order Id
rating Number Yes Rating score, range 1-5
comment String No Comment

Response

JSON response example:

{}

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found - Token not found
- Order not found
- Supplier not found
401 Unauthorized Unauthorized
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Notify order to a supplier (for testing)

Client call this endpoint to push notification of a list of ASSIGNING | IDLE order to a supplier Deny this request if supplier’s account status != ACTIVATED

curl -v 'https://apistg.ahamove.com/v1/order/notify_order' \
    -d "order_ids=4BWFRD,5NLFRD" \
    -d "token=5bd1e360eb44d72b76ce6905" \
    -d "supplier_id=84944309347"
    -d "noti_timeout=10"

HTTP Request

POST https://apistg.ahamove.com/v1/order/notify_order

Query Parameters

Parameter Type Required Description
token String Yes Admin/ Moderator token
order_ids String Yes List of order ids in string format, separated by commas
supplier_id Number Yes Supplier ID
noti_timeout Number No 16 by default
allow_busy Boolean No False by default. It allow Ops to push notification to supplier while he is busy
trip_distance Number No Trip distance
sound Boolean No Optional
max_cod Number No Optional

Response

JSON response example:

{
    "type": "order_dispatch",
    "order_ids": "4BWFRD,5NLFRD",
    "order_id": "4BWFRD",  #This field will be removed after all client app updated#
    "noti_timeout": 16,
    "notify_id": "5c974d548a5da551acc78640",
    "title": "New Assigning Order",
    "trip_distance": 30, # Optional
    "incentive_policy": "abc", # Optional
    "incentive_policy_highlight": "xyz", # Optional
    "score": 5, # Optional
    "max_cod": 500000 # Optional
}

Status-Code: 200 OK

Errors

Code Text Description
404 Not Found - Token not found
- Order not found
- Supplier not found
401 Unauthorized Unauthorized
406 Unauthorized Order status not valid
409 Conflict Supplier not online
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

SaaS APIs - OnWheel.io

AhaMove also provides several apis as a service (hence have fee charging), in some domain such as map problems, route optimization or geospatial analytics.

Route Optimization or Vehicle Routing Problem is a classic problem of logistic when we want to find optimal trips for a fleet of vehicles with many custom constraints such as time-window, max distance, capacity, etc...

SDVRP

API to solve the VRP problem with constraints and predifined depot(source) list, getting the optimal set of clusters for a number of vehicles. In another words, suppose that you have multiple stores in a city and want all deliveries will start from a stores nearest to the drop-off most.

curl -X POST \
  https://ep.ahamove.com/ro/sdvrp \
  -H 'Api-Key: {your_api_key}' \
  -H 'Content-Type: application/json' \
  -d '{"depots":[[10.710883,106.736404],[10.814225,106.717411]],"points":[[10.782877,106.704793,0],[10.792999,106.667045,1],[10.754883,106.689451,1],[10.765853,106.7027,1],[10.75872,106.69424,1],[10.710883,106.736404,1],[10.797516,106.618576,1],[10.8228811,106.6380496,1],[10.775009,106.649203,1],[10.727918,106.718238,1],[10.741123,106.659326,1],[10.778109,106.685502,1],[21.029733,105.841712,1],[10.794827,106.689322,1],[10.7856345,106.6952241,1],[10.790663,106.683842,1],[10.805706,106.701765,1],[10.8099,106.693527,1],[10.799145,106.717902,1],[10.814225,106.717411,1],[10.798143,106.712918,1],[10.806106,106.715016,1],[10.793423,106.709746,1],[10.799643,106.723635,1]],"min_vehicles":true,"min_parcels":4,"max_parcels":10,"vehicle_num":6,"dimensions":[{"name":"cod","max_capacity":10000000,"values":[0,175000,260000,180000,175000,285000,430000,175000,325000,185000,180000,925000,775000,175000,475000,185000,165000,315000,175000,175000,0,165000,165000,165000]}]}'

HTTP Request

POST https://ep.ahamove.com/ro/sdvrp

Api-Key: {your_api_key}

Parameters

# Parameters
{
    "depots":[[10.710883,106.736404],[10.814225,106.717411]],
    "points":[[10.782877,106.704793,0],[10.792999,106.667045,1],[10.754883,106.689451,1],[10.765853,106.7027,1],[10.75872,106.69424,1],[10.710883,106.736404,1],[10.797516,106.618576,1],[10.8228811,106.6380496,1],[10.775009,106.649203,1],[10.727918,106.718238,1],[10.741123,106.659326,1],[10.778109,106.685502,1],[21.029733,105.841712,1],[10.794827,106.689322,1],[10.7856345,106.6952241,1],[10.790663,106.683842,1],[10.805706,106.701765,1],[10.8099,106.693527,1],[10.799145,106.717902,1],[10.814225,106.717411,1],[10.798143,106.712918,1],[10.806106,106.715016,1],[10.793423,106.709746,1],[10.799643,106.723635,1]],
    "min_vehicles":true,
    "min_parcels":4,
    "max_parcels":10,
    "vehicle_num":6,
    "dimensions":[{"name":"cod","max_capacity":10000000,"values":[0,175000,260000,180000,175000,285000,430000,175000,325000,185000,180000,925000,775000,175000,475000,185000,165000,315000,175000,175000,0,165000,165000,165000]}]
}
Parameter Type Required Description
points Array Yes Array of delivery/dropoff coordinates, each coordinate is an array [lat,lng]
depots Array Yes Array of depot/pickup coordinates, each coordinate is an array [lat,lng]. Any vehicle has to start from nearest depot among this list.
vehicle_num Number Yes The number of available vehicles/drivers. By default a vehicle can travel maximum a trip. If your vehicle can travel 3 trips per shift, we can adjust the ratio to 1/3.
max_parcels Number No the vehicle capacity/the maximum number of parcels (~stop number) that a vehicle can carry (default is 20).
min_parcels Number No the minimum number of parcels that a driver need to carry
max_distance Number No the maximum distance that each driver can travel for a route.
point_max_distance Number No the maximum distance allowed from a stop point to the first point, this value by default is 30000 (metter). This way is to detect invalid stop point asap before taking a long time for route optimization (because api will throw status 400 right after finding invalid stop points. If this value is set to 0, this rule check will be ignored.
min_vehicles Boolean No (default is false), a flag indicates if the solution used the minimum number of vehicles it can or utilized all vehicles.
result_mode String No (default is COORDINATES), specify the format of output trip stop-point in COORDINATES or INDEX (based on input points index)
dimensions Array No a list of constraint objects, descibed below in details.

Dimensions

For example, we want to force the output vehicles must have total COD under 1mil, so we add a dimension object include COD value of each stop point, with name as 'COD' and max_capacity as 1000000.

 "dimensions": [{
                "values": [0,100,200,300,100,200,300,100,200,300,100,200,300,100,200,300,100,200,300,100],
                "name": "COD",
                "max_capacity": 1000
               }]

A dimension is a rule, based on a specific dimension (aspect) such as COD/Weight/Load etc that defined an upper hard limit that all vehicles/trips must be under.... Hence, a constraint object has 3 fields: values, name and max_capicity, where values are value of each stop point in that dimension distinguished by name , and max_capacity is the upper limit of all vehicles applied to the total of stop point values in that dimension.

Parameter Type Required Description
values Array Yes Array of load value of each stops, hence array length = 1 + deliveries.length.
name String Yes Name of this dimension.
max_capacity Number Yes Max capacity of a vehicle on this dimension

Response

JSON response example:

{
    "cluster":[[[10.814225,106.717411],[10.798143,106.712918],[10.793423,106.709746],[10.782877,106.704793],[10.7856345,106.6952241],[10.778109,106.685502],[10.790663,106.683842],[10.792999,106.667045],[10.775009,106.649203],[10.797516,106.618576],[10.8228811,106.6380496],[21.029733,105.841712]],[[10.710883,106.736404],[10.710883,106.736404],[10.727918,106.718238],[10.741123,106.659326],[10.754883,106.689451],[10.75872,106.69424],[10.765853,106.7027]],[[10.814225,106.717411],[10.814225,106.717411],[10.806106,106.715016],[10.799145,106.717902],[10.799643,106.723635],[10.805706,106.701765],[10.8099,106.693527],[10.794827,106.689322]]],
    "violated_points":[],
    "violated_cluster":[],
    "metrics":[{"distance":1569158.4,"count":12},{"distance":19513.4,"count":7},{"distance":11542.8,"count":8}],
    "performance":{"total_locations":25,"total_vehicle":3,"total_distance":1600214.5999999999,"total_running_time_second":1.3251516819000244}
}

Status-Code: 200 OK

Parameter Type Description
cluster Array an array of routes in which each array in the clusters represent an optimal route for a single vehicle.
violated_point Array an array of points that violated the constraints
violated_route Array set of routes that still violated the constraints of the problem (in the case which there is no solution satisfy the problem and the solver still try to find the best fit)

TWVRP

API to solve the SDVRP problem with time windows constraints. Time-windows constraints require delivery time of each stop point must be within its given time window.

curl -X POST \
  https://ep.ahamove.com/ro/twvrp \
  -H 'Api-Key: {your_api_key}' \
  -H 'Content-Type: application/json' \
  -d '{"depots":[[10.710883,106.736404],[10.814225,106.717411]],"points":[[10.782877,106.704793,0],[10.792999,106.667045,1],[10.754883,106.689451,1],[10.765853,106.7027,1],[10.75872,106.69424,1],[10.710883,106.736404,1],[10.797516,106.618576,1],[10.8228811,106.6380496,1],[10.775009,106.649203,1],[10.727918,106.718238,1],[10.741123,106.659326,1],[10.778109,106.685502,1],[21.029733,105.841712,1],[10.794827,106.689322,1],[10.7856345,106.6952241,1],[10.790663,106.683842,1],[10.805706,106.701765,1],[10.8099,106.693527,1],[10.799145,106.717902,1],[10.814225,106.717411,1],[10.798143,106.712918,1],[10.806106,106.715016,1],[10.793423,106.709746,1],[10.799643,106.723635,1]],"min_vehicles":true,"min_parcels":4,"max_parcels":10,"vehicle_num":6,"dimensions":[{"name":"cod","max_capacity":10000000,"values":[0,175000,260000,180000,175000,285000,430000,175000,325000,185000,180000,925000,775000,175000,475000,185000,165000,315000,175000,175000,0,165000,165000,165000]}]}'

HTTP Request

POST https://ep.ahamove.com/ro/twvrp

Header

Api-Key: {your_api_key}

Parameters

# Parameters
{
    "depots": [[10.795775, 106.648416], [10.758132, 106.719056]], 
    "points": [[10.757285, 106.705133, 1], [10.8287929, 106.716781, 1], [10.7578049, 106.7191207, 1], [10.7484371, 106.6899893, 1], [10.8030974, 106.6425775, 1], [10.760248, 106.708708, 1], [10.75708, 106.653058, 1], [10.7555112, 106.6745896, 1], [10.751636, 106.6206908, 1]], 
    "time_windows": [[420, 1140], [1140, 1200], [420, 1140], [1080, 1140], [1080, 1140], [1140, 1200], [1080, 1140], [1140, 1200], [1080, 1140]],
    "max_parcesl": 3, 
    "min_vehicles": true, 
    "vehicle_num": 9, 
    "result_mode": "INDEX", 
    "transport_mode": "1N"
}
Parameter Type Required Description
points Array Yes Array of delivery/dropoff coordinates, each coordinate is an array [lat,lng]
depots Array Yes Array of depot/pickup coordinates, each coordinate is an array [lat,lng]. Any vehicle has to start from nearest depot among this list.
vehicle_num Number Yes The number of available vehicles/drivers. By default a vehicle can travel maximum a trip. If your vehicle can travel 3 trips per shift, we can adjust the ratio to 1/3.
time_windows Array Yes an array, each item is an array of 2 timestamps of time windows in minutes of intraday. For example, if a stop requires delivery in 17:00-18:00, so this time-window value will be [1020,1080] since 1020=17x60 and 1080=18x60
vehicle_speed Number No The speed of vehicle to convert travelling distance into travelling time, this value by default is 200 (meter/minute)~1km/5minute
max_parcels Number No the vehicle capacity/the maximum number of parcels (~stop number) that a vehicle can carry (default is 20).
min_parcels Number No the minimum number of parcels that a driver need to carry
max_distance Number No the maximum distance that each driver can travel for a route.
point_max_distance Number No the maximum distance allowed from a stop point to the first point, this value by default is 30000 (metter). This way is to detect invalid stop point asap before taking a long time for route optimization (because api will throw status 400 right after finding invalid stop points. If this value is set to 0, this rule check will be ignored.
min_vehicles Boolean No (default is false), a flag indicates if the solution used the minimum number of vehicles it can or utilized all vehicles.
result_mode String No (default is COORDINATES), specify the format of output trip stop-point in COORDINATES or INDEX (based on input points index)
dimensions Array No a list of constraint objects, descibed below in details.

Dimensions

For example, we want to force the output vehicles must have total COD under 1mil, so we add a dimension object include COD value of each stop point, with name as 'COD' and max_capacity as 1000000.

 "dimensions": [{
                "values": [0,100,200,300,100,200,300,100,200,300,100,200,300,100,200,300,100,200,300,100],
                "name": "COD",
                "max_capacity": 1000
               }]

A dimension is a rule, based on a specific dimension (aspect) such as COD/Weight/Load etc that defined an upper hard limit that all vehicles/trips must be under.... Hence, a constraint object has 3 fields: values, name and max_capicity, where values are value of each stop point in that dimension distinguished by name , and max_capacity is the upper limit of all vehicles applied to the total of stop point values in that dimension.

Parameter Type Required Description
values Array Yes Array of load value of each stops, hence array length = 1 + deliveries.length.
name String Yes Name of this dimension.
max_capacity Number Yes Max capacity of a vehicle on this dimension

Response

JSON response example:

{
    "cluster": [[[1, 1055], [1, 1080], [4, 1113], [8, 1140]], [[0, 1058], [5, 1080], [7, 1109], [9, 1129]], [[1, 1103], [3, 1118], [6, 1140], [2, 1183]]], 
    "violated_points": [], 
    "violated_cluster": [], 
    "metrics": [{"distance": 8490.1, "count": 4}, {"distance": 11522.1, "count": 4}, {"distance": 10190.9, "count": 4}], 
    "performance": {"total_locations": 10, "total_vehicle": 3, "total_distance": 30203.1, "total_running_time_second": 0.48145389556884766}
}

Status-Code: 200 OK

Parameter Type Description
cluster Array an array of routes in which each array in the clusters represent an optimal route for a single vehicle, along with its time of arrival.
violated_point Array an array of points that violated the constraints
violated_route Array set of routes that still violated the constraints of the problem (in the case which there is no solution satisfy the problem and the solver still try to find the best fit)

GEOCODE

API to translate address text into coordinates. Unlike other data providers, AhaMove provide a simple endpoint that utilizes multiple data sources behind the scene to make sure we have a reliable, cost-effective and measurable geocoder.

curl -X POST \
  https://ep.ahamove.com/geocode/geocode \
  -H 'Api-Key: {your_api_key}' \
  -H 'Content-Type: application/json' \
  -d '{"address":"341 Sư Vạn Hạnh, Phường 10, Quận 10, Hồ Chí Minh, Vietnam"}'

HTTP Request

POST https://ep.ahamove.com/geocode/geocode

Header

Api-Key: {your_api_key}

Parameters

# Parameters
{
  "addresss": "341 Sư Vạn Hạnh, Phường 10, Quận 10, Hồ Chí Minh, Vietnam"
}
Parameter Type Required Description
address String Yes The address text of location to be translated into coordinate. We recommend the address should have the following standard format: , , , (the house number and street name can be replaced by a building name such as "Chung Cư Pearl Plaza", so on...) which will help the geocoder to find the most accurate location.

Response

JSON response example:

{
  "formattedAddress": "341 Sư Vạn Hạnh, Phường 10, Quận 10, Thành phố Hồ Chí Minh 700000, Vietnam",
  "latitude": 10.7690556,
  "longitude": 106.6711495,
  "types": [
      "street_address"
  ],
  "provider": "google",
  "address": "341 Sư Vạn Hạnh, Phường 10, Quận 10, Thành phố Hồ Chí Minh",
  "source": "google"
}

Status-Code: 200 OK

Parameter Type Description
formattedAddress String the formatted address returned by geocoder.
latitude Number latitude of the coordinate
longitude Number longitude of the coordinate

Webhook

# callback data
{
  "_id" : "00LS",
  "status" : "COMPLETED",
  "city_id" : "SGN",
  "service_id" : "SGN-BIKE",

  # Other order details...
}

Your app will need to provide a webhook URL to receive order updated events from AhaMove. AhaMove will call this API each time the order has updates. For example, AhaMove will call POST below url when a supplier completes the order

http://example.com/partner/update_ahamove_status

How to test Webhook

  1. Implement webhook url to receive order_id & status, then send AhaMove the URL to config
  2. Use this link download to install AhaMove Driver staging app on Android device
  3. Register an account, then login and go online
  4. Use above order/create API to create an order within 5km from the supplier location
  5. The supplier app will receive a notification, click on the notification to accept the order
  6. AhaMove server will trigger an event to webhook URL with ACCEPTED status
  7. Try to Board or Complete on the supplier app, AhaMove server will trigger events to webhook URL with according order statuses

Order Status

Main Status (status)

Status Description
IDLE Order confirmed
ASSIGNING Finding a supplier
ACCEPTED Once supplier accepts the order, the order status will be changed to ACCEPTED
IN PROCESS When the supplier collects the food at the restaurant, he will click “Pick up” and the order status will be changed to IN PROCESS
COMPLETED When the supplier completes the order, the order status will be changed to COMPLETED
CANCELLED - If the supplier cancels the order, the order status will be changed to CANCELLED, cancel_by_user is set to False
- If the user cancels the order, the order status will be changed to CANCELLED, cancel_by_user is set to True
- If there is no suppliers accepting order after 15 minutes, the order status will be changed to CANCELLED, cancel_by_user is set to False, and cancel_comment is set to “Auto cancel, no driver accepted”

Delivery Status (path[x].status, x > 0)

Sub Status (sub_status)

Flow Diagram

Order flow (P2P)

P2p

Changelog

API versions and changes

2020-10-07

2020-02-14 (Current version)

2019-12-30

2019-11-07

2019-10-06

2019-09-29

2019-09-28

2019-09-03

2019-07-22