Armada Delivery API order placement

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.

Authentication

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:

Open Sidebar by clicking on the Menu icon in the top left corner of the screen
Open Settings page
Open API settings page
Click on "Generate API Key" button

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

Order Placement (Creation)

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"
    }
}'

Response

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"
}

Fetching orders

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:

orderCode: The Id Of the delivery within Armada

Response

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.

Canceling orders `beta`

To cancel an order, you will need to make an HTTP POST request to the following endpoint:

https://api.armadadelivery.com/v0/deliveries/:orderCode/cancel

Where:

id: The Id Of the delivery within Armada

Webhooks

To receive real-time updates on the status of orders placed through your app, you can provide a webhook URL in the Armada delivery Merchant UI. Our API will send a POST request to this URL any time the status of an order changes.

The list of the statuses:

pending: the order has been received and is waiting to be dispatched to a driver
dispatched: the order has been dispatched to a driver who is on his way to the merchant
en route: the order has been picked up from the merchant and is being delivered to the customer
complete: the order has been successfully delivered
canceled: the order has been canceled from the merchant
failed: the order has failed to find a driver

Response

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,
driver: An object containing the driver name and phone number.
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.

In headers:

Authorization: The value of your order-webhook-key you provide when you create the order.

Sandbox Access

Through our sandbox environment, you'll be able to play around with the integration and test it for your app.

The Api URL of the Prodlike environment is: https://staging.merchant.armadadelivery.com/

The test account credentials:

Email: mohamed+merchant@armadadelivery.com
Password: Armada2020!

We highly recommend you to create a new branch so that your tests don't interfere with others.

Keep in mind that this account is shared with other testers. If you want your own account please signup, then reach out to our support to provide them with the merchant name you created and we will topup the account.

Hope this document was helpful, in case of any feedback please don't hesitate to share it with us. It's more than welcome.

Made with 💙 by the Armada Tech Heroes

Armada Delivery API order placement

Authentication

Order Placement (Creation)

Response

Fetching orders

Response

Canceling orders beta

Webhooks

Response

Sandbox Access

Canceling orders `beta`