# Branch Management

# Introduction

In branch management, you can create, edit, fetch, or delete branches via API using API Keys. However, we have two kinds of keys:

Main Key: This is the root of all other keys. You can only have one in your account. With this main key, you can create other keys and branches. You can regenerate it anytime, but you can't share it with anyone!
Regular API Keys: These are the standard API Keys. Each key is responsible for a branch. You can share it with your team or clients. Each client can have their own branch with their own key!

# Rules

The main key:
- has no branch.
- is required to create a new branch.
- is required to get all branches.
The regular key:
- has a branch.
- is required to get a specific branch.
- is required to update a specific branch.
Both the main key and regular key can be used to delete a specific branch.

If you remove a branch, the regular API keys linked to it will also be deleted.

# Note

To test your work on the sandbox or staging API, please refer to the Environments section for detailed instructions.

# Generate API Main-Key

From the merchant dashboard:

Open Sidebar by clicking on the Menu icon in the top left corner of the screen.
Open Settings page.
Open API settings page.
In the Main API Keys section, Click on "Generate new key" button.

You will have a main key with this regex main_[a-z0-9]{31}. Example: main_791239217df38440b8a48dclsruc444

# Create New Branch

To create a branch, you will need to make an HTTP POST request to the following endpoint:

https://staging.api.armadadelivery.com/v0/branches

https://api.armadadelivery.com/v0/branches

Use the API Main Key (See Introduction)

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

name: Branch name, Between 2 and 75 String - Required
phone: Branch phone number String - Required
address: The branch address Object - Required
- location: Geo-location address Object - Required
  - latitude: Float - Required
  - longitude: Float - Required
- firstLine: A Complete Regular Address, It’s important for drivers as a human readable address String - Optional
webhook: Webhook URL to receive order status updates on your end String - Optional

Note 💡

If you don't specify a firstLine, We will create it using the nearest location in our databases. However, keep in mind that the automatically generated address may not be entirely accurate. For better precision, consider providing specific details whenever possible.

# Request Example

curl --location --request POST 'https://api.armadadelivery.com/v0/branches' \
--header 'Authorization: Key [YOUR API MAIN KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "NAQSH",
    "phone": "+96500000000",
    "address": {
        "location":{
	        "latitude": 29.192375,
	        "longitude": 48.111894
		},
        "firstLine": "Abu Hassaniah, Block 10, St 60, 36B"
    },
    "webhook": "https://webhook.site/378d8934-0de5-48cd-9ed4-aeda171faabc"
}'

const apiMainKey = '[YOUR API MAIN KEY]'; // Replace with your actual API Main key

fetch('https://api.armadadelivery.com/v0/branches', {
  method: 'POST',
  headers: {
    'Authorization': `Key ${apiMainKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "name": "NAQSH",
    "phone": "+96500000000",
    "address": {
      "location": {
        "latitude": 29.192375,
        "longitude": 48.111894,
      },
      "firstLine": "Abu Hassaniah, Block 10, St 60, 36B"
    },
    "webhook": "https://webhook.site/378d8934-0de5-48cd-9ed4-aeda171faabc"
  })
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

func main() {
	apiKey := "[YOUR API MAIN KEY]" // Replace with your actual API Main key
	url := "https://api.armadadelivery.com/v0/branches"

	data := map[string]interface{}{
		"name": "NAQSH",
		"phone": "+96500000000",
		"address": map[string]interface{}{
			"location": map[string]float64{
				"latitude":  29.192375,
				"longitude": 48.111894,
			},
			"firstLine": "Abu Hassaniah, Block 10, St 60, 36B",
		},
		"webhook": "https://webhook.site/378d8934-0de5-48cd-9ed4-aeda171faabc",
	}

	jsonData, err := json.Marshal(data)
	if err != nil {
		fmt.Println("Error encoding JSON:", err)
		return
	}

	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	if err != nil {
		fmt.Println("Error creating request:", err)
		return
	}

	req.Header.Set("Authorization", "Key "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	// ...
}

The response will include the details from your request body, along with the _id and key associated with the branch.

# Response Schema

{
	_id: String,
	phone: String,
	name: String
	address: {
	  location:{
		  latitude: Number,
		  longitude: Number,
	  },
	  firstLine: String
	},
	key: String
	webhook: String
}

# Get All Branches

To get all branches, you will need to make an HTTP GET request to the following endpoint:

https://staging.api.armadadelivery.com/v0/branches

https://api.armadadelivery.com/v0/branches

Use the API Main Key (See Introduction)

# Request Example

curl --location --request GET 'https://api.armadadelivery.com/v0/branches' \
--header 'Authorization: Key [YOUR API MAIN KEY]'

fetch('https://api.armadadelivery.com/v0/branches', {
    method: 'GET',
    headers: {
        'Authorization': `Key [YOUR API MAIN KEY]`,
    }
})
.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/v0/branches", nil)
    if err != nil {
        fmt.Println(err)
    }
    req.Header.Set("Authorization", "Key [YOUR API MAIN KEY]")

    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

You will get an array of data:

[
	{
		_id: String,
		phone: String,
		name: String
		address: {
		location:{
			latitude: Number,
			longitude: Number,
		},
		firstLine: String
		},
		api:[
			{
				key: String, webhook: String
			}
		]
	},
	// ...
]

We provide the api as an array of objects because some branches may have multiple regular keys. You can't assign multiple keys to a branch via the API, but this feature is available only through the merchant dashboard.

# Get One Branch

To get one branch, you will need to make an HTTP GET request to the following endpoint:

https://staging.api.armadadelivery.com/v0/branches/:id

https://api.armadadelivery.com/v0/branches/:id

id: Parameter, The branch ID String - Required

# Request Example

(e.g id = 5eef2043bfa02f001c17b229)

curl --location --request GET 'https://api.armadadelivery.com/v0/branches/5eef2043bfa02f001c17b229' \
--header 'Authorization: Key [YOUR API KEY]'

fetch('https://api.armadadelivery.com/v0/branches/5eef2043bfa02f001c17b229', {
    method: 'GET',
    headers: {
        'Authorization': `Key [YOUR API KEY]`,
    }
})
.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/v0/branches/5eef2043bfa02f001c17b229", nil)
    if err != nil {
        fmt.Println(err)
    }
    req.Header.Set("Authorization", "Key [YOUR API KEY]")

    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

{
	_id: String,
	phone: String,
	name: String
	address: {
	  location:{
		  latitude: Float,
		  longitude: Float
	  },
	  firstLine: String
	},
	key: String,
	webhook: String
}

# Update Branch

To update a branch, you will need to make an HTTP PUT request to the following endpoint:

https://staging.api.armadadelivery.com/v0/branches/:id

https://api.armadadelivery.com/v0/branches/:id

id: Parameter, The branch ID String - Required

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

name: Branch name, Between 2 and 75 String - Optional
phone: Branch phone number String - Optional
address: The branch address Object - Optional
- location: Geo-location address Object - Optional
  - latitude: Float
  - longitude: Float
- firstLine: A Complete Regular Address, It’s important for drivers as a human readable address String - Optional
webhook: Webhook URL to receive order status updates on your end String - Optional

# Request Example

(e.g id = 5eef2043bfa02f001c17b229)

curl --location --request PUT 'https://api.armadadelivery.com/v0/branches/5eef2043bfa02f001c17b229' \
--header 'Authorization: Key [YOUR API KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Alhambra Grill",
	"webhook": "https://typedwebhook.tools/webhook/415777a9-7722-4d74-8f32-0d8ec8178915"
}'

fetch('https://api.armadadelivery.com/v0/branches/5eef2043bfa02f001c17b229', {
    method: 'PUT',
    headers: {
         'Authorization': `Key [YOUR API KEY]`,
         'Content-Type': 'application/json'
     },
    body: JSON.stringify({
        "name": "Alhambra Grill",
        "webhook": "https://typedwebhook.tools/webhook/415777a9-7722-4d74-8f32-0d8ec8178915"
    })
})
.then(response => response.json())
.then((data) => console.log(data))
.catch((error) => console.error('Error:', error));

func main() {
    jsonData := []byte(`{
        "name": "Alhambra Grill",
        "webhook": "https://typedwebhook.tools/webhook/415777a9-7722-4d74-8f32-0d8ec8178915"
    }`)
    req, err := http.NewRequest("PUT", "https://api.armadadelivery.com/v0/branches/5eef2043bfa02f001c17b229", bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Println("Error:", err)
    }
    req.Header.Set("Authorization", "Key [YOUR API KEY]")
    req.Header.Set("Content-Type", "application/json")

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

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

# Response Schema

{
	_id: String,
	phone: String,
	name: String
	address: {
	  location:{
		  latitude: Float,
		  longitude: Float
	  },
	  firstLine: String
	},
	key: String,
	webhook: String
}

# Delete Branch

To delete a branch, you will need to make an HTTP DELETE request to the following endpoint:

https://staging.api.armadadelivery.com/v0/branches/:id

https://api.armadadelivery.com/v0/branches/:id

id: Parameter, The branch ID String - Required

# Request Example

(e.g id = 5eef2043bfa02f001c17b229)

curl --location --request DELETE 'https://api.armadadelivery.com/v0/branches/5eef2043bfa02f001c17b229' \
--header 'Authorization: Key [YOUR API KEY]'

fetch('https://api.armadadelivery.com/v0/branches/5eef2043bfa02f001c17b229', {
    method: 'DELETE',
    headers: {
        'Authorization': `Key [YOUR API KEY]`,
    }
})
.then(response => response.json())
.then((data) => console.log(data))
.catch((error) => console.error('Error:', error));

func main() {
    req, err := http.NewRequest("DELETE", "https://api.armadadelivery.com/v0/branches/5eef2043bfa02f001c17b229", nil)
    if err != nil {
        fmt.Println(err)
    }
    req.Header.Set("Authorization", "Key [YOUR API KEY]")

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

# Response

If successful, expect a response with HTTP status code 204.