# Delivery

# Introduction

Using our order management API, you can seamlessly dispatch orders to Armada drivers and access key details, including fees, delivery estimates, tracking links, and more. Our service is available in Kuwait, Bahrain, and Saudi Arabia (KSA).

# Order Making

Place an order via HTTP POST at:

POST
https://api.armadadelivery.com/v1/deliveries

The body of the request should be in JSON format and include the following parameters:

reference: Order reference ID String - Required
origin_type: Should be "branch" String - Required
origin: Contains information about the origin Object - Required
- branch: Branch reference ID String - Required
destination_type: Type of the destination, can be location_components, kuwait_components etc .. See more String - Required
destination: Contains the customer's destination information Object - Required
- contact: Customer contact information Object - Required
  - name: Customer name String - Required
  - phone: Customer phone String - Required
- address_components: Customer address information Object - Required
  - The available values vary depending on the destination type. See the examples in the code below
- floor: Floor number String - Optional
- apartment: Apartment number String - Optional
- instructions: Extra delivery instructions String - Optional
payment: Payment details Object - Required
- amount: Total amount for the order Number - Required
- type: Payment type, can be "paid" or "cash" String - Required
scheduled_date: Desired start time for the order ISO Date - Optional
- The specified time must be later than the current time. If the time is within 30 minutes, the order will be processed immediately.

# Create order

You can now select the appropriate destination type based on your location. Choose geo-location for universal deliveries or other options based on your country.

Remember to include your Armada-Access-Token in the request headers. If you don't have one, please refer to the Authentication page to learn how to obtain it.

For the security, we recommend including a security key in the headers of your order:

Order-Webhook-Key: Webhook key must be between 12-32 characters String - Optional

When you receive an order update via your webhook, the Order-Webhook-Key will be included in the headers for security purposes. See webhook for more details.

curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "ORD-4574CTH",
  "origin_type": "branch",
  "origin": {
    "branch": "66fd56bc95023b0038183be2"
  },
  "destination_type": "location_components",
  "destination": {
    "contact": {
      "name": "zakaria",
      "phone": "+212680985566"
    },
    "address_components": {
      "first_line": "123 Main St kuwait", // optional (human readable helper for drivers)
      "location": {
        "latitude": 29.355069903470575,
        "longitude": 47.80469652165224
      }
    },
    "floor": "2",
    "apartment": "12A",
    "instructions": "Leave the order by the front door and ring the bell"
  },
  "payment": {
    "amount": "7.000",
    "type": "cash"
  }
}'

curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "ORD-654789123",
  "origin_type": "branch",
  "origin": {
    "branch": "66ec0dd019f1110031e6ffc0"
  },
  "destination_type": "kuwait_components",
  "destination": {
    "contact": {
      "name": "Chahd",
      "phone": "+96566473829"
    },
    "address_components": {
      "area": "Abdullah Mubarak Al-Sabah",
      "block": "5",
      "street": "St 503",
      "building": "123"
    },
    "floor": "2",
    "apartment": "12A",
    "instructions": "Put it in front of the door and ring the bell"
  },
  "payment": {
    "amount": "7.000",
    "type": "paid"
  }
}'

curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "ORD-9876BHR",
  "origin_type": "branch",
  "origin": {
    "branch": "66fd56bc95023b0038183be2"
  },
  "destination_type": "bahrain_components",
  "destination": {
    "contact": {
      "name": "Rajae",
      "phone": "+97333985678"
    },
    "address_components": {
      "area": "Adliya",
      "block": "338",
      "street": "Road 2819",
      "building": "150"
    },
    "floor": "2",
    "apartment": "12A",
    "instructions": "Leave the order by the front door and ring the bell"
  },
  "payment": {
    "amount": "10.000",
    "type": "paid"
  }
}'

curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "ORD-1234KSA",
  "origin_type": "branch",
  "origin": {
    "branch": "66fd56bc95023b0038183be2"
  },
  "destination_type": "ksa_components",
  "destination": {
    "contact": {
      "name": "Amal",
      "phone": "+966501234567"
    },
    "address_components": {
      "city": "Al Olaya",
      "street": "King Fahd Road",
      "district": "Al Olaya District",
      "building": "456"
    },
    "floor": "3",
    "apartment": "8B",
    "instructions": "Please leave the package at the reception."
  },
  "payment": {
    "amount": "15.000",
    "type": "cash"
  }
}'

curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "ORD-5678KSA",
  "origin_type": "branch",
  "origin": {
    "branch": "66fd56bc95023b0038183be2"
  },
  "destination_type": "ksa_short_components",
  "destination": {
    "contact": {
      "name": "Bashir",
      "phone": "+966501234567"
    },
    "address_components": {
      "short_address": "RFNB4718"
    },
    "floor": "3",
    "apartment": "8B",
    "instructions": "Leave the package with the security guard."
  },
  "payment": {
    "amount": "20.000",
    "type": "paid"
  }
}'

# Response Schema

After successful completion, our API will provide a JSON response containing the following parameters:

code: Delivery ID within Armada String
deliveryFee: Cost of the delivery Number
amount: Order amount set by the merchant Number
customerAddress: Customer address generated by Armada based on platform data String
customerLocation: Object
- latitude: Latitude of the customer location Float
- longitude: Longitude of the customer location Float
customerName: Customer name String
customerPhone: Customer phone number String
orderStatus: Status of the order. (see webhooks status for more details) String
estimatedDistance: Estimated distance from pickup to customer destination in meters Number
estimatedDuration: Estimated duration from pickup to customer destination in seconds Number
driver: Driver data Object
- name: Driver name String
- phoneNumber: Driver phone String
trackingLink: Link to a public page showing live delivery progress (share it with your client ) URL
qrCodeLink: Link to the QR code for the driver to scan if not performed within the merchant dashboard URL
orderCreatedAt: Date of delivery creation ISO DATE
currency: Currency used for this delivery String

# Response Example

JSON
{
  "code": "E8E5653A05",
  "deliveryFee": 194.25,
  "amount": 17.5,
  "customerAddress": "Abdullah Mubarak Al-Sabah, Block 5, St 503",
  "customerLocation": {
    "latitude": 29.242885,
    "longitude": 47.894161
  },
  "customerName": "mohamed",
  "customerPhone": "+96551234567",
  "orderStatus": "pending",
  "estimatedDistance": 24857,
  "estimatedDuration": 1772.55,
  "driver": {
    "name": "Yazid",
    "phoneNumber": "+9650000000"
  },
  "trackingLink": "https://tracking.armadadelivery.com/4c04d9b8-c358-4b0e-b81c-846fd840beea",
  "qrCodeLink": "https://armada-prod.s3.eu-central-1.amazonaws.com/qrCodes/a6c8b061036f988334937de367b6e2ae.svg",
  "orderCreatedAt": "2024-02-21T17:18:04.214Z",
  "currency": "KWD"
}

# Get Order

Get order details via HTTP GET at:

GET
https://api.armadadelivery.com/v1/deliveries/:code

code: Code returned by order creation String - Required

# Request Example

(e.g code = E8E5653A05)

Remember to include your Armada-Access-Token in the request headers. If you don't have one, please refer to the Authentication page to learn how to obtain it.

curl --location --request GET 'https://api.armadadelivery.com/v1/deliveries/E8E5653A05' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]'

fetch('https://api.armadadelivery.com/v1/deliveries/E8E5653A05', {
    method: 'GET',
    headers: {
        'Armada-Access-Token': '[YOUR ACCESS TOKEN]',
    }
})
.then(response => response.json())
.then((data) => console.log(data))
.catch((error) => console.error('Error:', error));

func main() {
    req, err := http.NewRequest("GET", "https://api.armadadelivery.com/v1/deliveries/E8E5653A05", nil)
    if err != nil {
        fmt.Println(err)
    }
    req.Header.Set("Armada-Access-Token", "[YOUR ACCESS TOKEN]")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

# Response Schema

For more details see Response Schema and Example of the previous section.

{
  code: String,
  deliveryFee: Number,
  amount: Number,
  customerAddress: String,
  customerLocation: {
    latitude: Number,
    longitude: Number,
  },
  customerName: String,
  customerPhone: String,
  orderStatus: String,
  estimatedDistance: Number,
  estimatedDuration: Number,
  driver: {
    name: String,
    phoneNumber: String,
  },
  trackingLink: String,
  qrCodeLink: String,
  orderCreatedAt: Date,
  currency: String,
}

# Cancel Order

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

POST
https://api.armadadelivery.com/v1/deliveries/:code/cancel

code: Code returned by order creation String - Required

# Request Example

(e.g code = E8E5653A05)

Remember to include your Armada-Access-Token in the request headers. If you don't have one, please refer to the Authentication page to learn how to obtain it.

curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries/E8E5653A05/cancel' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--data ''

fetch('https://api.armadadelivery.com/v1/deliveries/E8E5653A05/cancel', {
  method: 'POST',
  headers: {
    'Armada-Access-Token': '[YOUR ACCESS TOKEN]'
  },
})
.then(response => response.ok ? console.log('Delivery successfully cancelled') : console.error('Failed to cancel delivery'))
.catch(error => console.error('Error cancelling delivery:', error));

func main() {
	url := "https://api.armadadelivery.com/v1/deliveries/E8E5653A05/cancel"
	accessToken := "[YOUR ACCESS TOKEN]"
    
	req, err := http.NewRequest("POST", url, nil)
	if err != nil {
		fmt.Println("Error creating request:", err)
		return
	}

	req.Header.Set("Armada-Access-Token", accessToken)

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error sending request:", err)
		return
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		fmt.Println("Failed to cancel delivery")
		return
	}

	fmt.Println("Delivery successfully cancelled")
}

# Response

Upon successful cancellation, you will receive a 200 status code.
For failures, you will receive a 400 status code.
Alternatively, you may receive a 404 status code for other failures.