Welcome to the Armada delivery web app API documentation. Our API allows you to integrate your ordering app with our delivery service, enabling your customers to place orders for delivery directly from your app. This documentation will provide you with all the necessary information to integrate your app with our API, including authentication, request format, and webhooks for real-time updates.
To use our API, you will need to generate an API key through the Armada Merchant UI. For that, our shared customer (Subscribed business), needs to:
Once you have the API key, you will need to include it in the headers of all API requests as the "Authorization" parameter, prefixed by the word Key.
Eg: Key somerandomkey-sdfsdfqmk
To place an order, you will need to make an HTTP POST request to the following endpoint:
https://api.armadadelivery.com/v0/deliveries
For the sandbox environment please use the following domain name: https://staging.api.armadadelivery.com/
The body of the request should be in JSON format and include the following parameters:
platformName: refer to the platform creating the delivery (Required).platformData: Contains the data required to create the delivery, more details below (Required):
orderId: The Id of the Order in the platform (Required),name: The Customer Name (Required),phone: The customer Phone (Required),area: The most Important param in the address components and should match our areas spelling (Required in case no location is provided),block: One of the address components (Required in case no location is provided),street: One of the address components (Required in case no location is provided),buildingNumber: One of the address components (Required in case no location is provided),floor: One of the address components used,apartment: One of the address components ,instructions: Extra instructions or information to the driver,amount: The order Amount used incase of chash payment mean (Required),scheduledAt: The order datetime you want the order to start at. The provided date should imperatively be later than now. If it is earlier than now + 30 minutes, the order will be submitted as a live one,paymentType: It should be 'paid' or 'cash',location: The location Of the customer { latitude: '', longitude: '' } (Required in case the Full address is not provided).For increased security, we recommend including a security key in the headers of your order:
order-webhook-key: Webhook key must be between 12-32 characters. (recommended)When you receive an order update via your webhook, the order-webhook-key will be included in the headers as an Authorization key for security purposes. see webhooks
Example request:
curl --location --request POST 'https://api.armadadelivery.com/v0/deliveries' \
--header 'Authorization: Key YOUR API KEY' \
--header 'order-webhook-key: vE6gH8Rt2L1sK9w' \
--header 'Content-Type: application/json' \
--data-raw '{
"platformName": "pos",
"platformData": {
"orderId": "OrderId",
"name": "mohamed",
"phone": "15245635895",
"area": "Abdullah Mubarak Al-Sabah",
"block": "5",
"street": "St 503",
"buildingNumber": "123",
"amount": "5.000",
"paymentType": "paid"
}
}'
For Saudi Arabia users, You'll need to provide the shortAdress property to set the customer location:
shortAddress: The short address version of the national-address (Required).You don't need to put "area, block, street, buildingNumber, floor, apartment, instructions", Just a shortAddress.
Example request:
curl --location --request POST 'https://api.armadadelivery.com/v0/deliveries' \
--header 'Authorization: Key YOUR API KEY' \
--header 'order-webhook-key: vE6gH8Rt2L1sK9w' \
--header 'Content-Type: application/json' \
--data-raw '{
"platformName": "pos",
"platformData": {
"orderId": "145as5",
"name": "zakaria",
"phone": "055445874",
"shortAddress": "RRAA2062",
"amount": "7.000",
"paymentType": "paid"
}
}'
Upon successful completion, our API will return a JSON response with the following parameters:
code: The Id Of the delivery within Armada,deliveryFee: The cost of the Delivery,amount: The order Amount of the order set by the merchant,customerAddress: The customer Address generated by Armada based on the data sent by the Platform,customerLocation: The customer Location { latitude: '', longitude: '' } based on the data sent by the platform,customerName: Customer Name,customerPhone: Customer Phone,orderStatus: The Order Status,estimatedDistance: Estimated Distance from the pick up to the customer location in Meters,estimatedDuration: Estimated Duration from the pick up to the customer location in Seconds,trackingLink: A link to a public Page showing a live of the delivery progress,qrCodeLink: A link to the QR code, to show to the driver, to scan the delivery in case the scan is not performed within the merchant dasboard,orderCreatedAt: Date of the Delivery Creation,currency: The currency used for this delivery.Example response:
{
"code": "0BAB9A5586",
"deliveryFee": 2,
"amount": 5,
"customerAddress": "Abdullah Mubarak Al-Sabah, Block 5, St 503",
"customerLocation": {
"latitude": 29.242885,
"longitude": 47.894161
},
"customerName": "mohamed",
"customerPhone": "15245635895",
"orderStatus": "pending",
"estimatedDistance": 24857,
"estimatedDuration": 1772.55,
"trackingLink": "undefined/tracking/d33ca2f3-ca06-4d5a-af70-fb752c6fb80a",
"qrCodeLink": "https://armada-sand.s3.amazonaws.com/qrCodes/aa256d1bc094bda2e45f99db28a03997.svg",
"orderCreatedAt": "2019-12-26T10:35:08.612Z",
"currency": "KWD"
}
To fetch an order, you will need to make an HTTP GET request to the following endpoint:
https://api.armadadelivery.com/v0/deliveries/:orderCode
Where: