# `Deputy.Locations`
[🔗](https://github.com/sgerrand/ex_deputy/blob/v0.4.0/lib/deputy/locations.ex#L1)

Functions for interacting with locations (companies) in Deputy.

# `archive`

```elixir
@spec archive(Deputy.t(), integer()) :: {:ok, map()} | {:error, Deputy.Error.t()}
```

Archive a location.

## Parameters

- `client`: A Deputy client.
- `id`: The ID of the location to archive.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.archive(client, 1)
    {:ok, %{"success" => true}}

# `create`

```elixir
@spec create(Deputy.t(), map()) :: {:ok, map()} | {:error, Deputy.Error.t()}
```

Add a new location.

## Parameters

- `client`: A Deputy client.
- `attrs`: A map containing the new location details.

## Location parameters

- `strWorkplaceName`: String naming the workplace.
- `strWorkplaceCode`: A string with a length of 3 allowing you to define a short code for the location.
- `strAddress`: String of the location's address.
- `strAddressNotes`: Optional. Notes about the address.
- `intParentCompany`: Optional. Integer ID of parent company.
- `intIsWorkplace`: Boolean (1 - True, 0 - False) whether the location is considered a workplace.
- `intIsPayrollEntity`: Boolean (1 - True, 0 - False) whether the location has payroll setup.
- `strTimezone`: Timezone for the workplace using TZ database naming.
- `strPayrollExportCode`: Optional. String naming what to use as a code for payroll exports.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> attrs = %{
    ...>   strWorkplaceName: "New Location",
    ...>   strWorkplaceCode: "NLC",
    ...>   strAddress: "123 Test St",
    ...>   intIsWorkplace: 1,
    ...>   intIsPayrollEntity: 1,
    ...>   strTimezone: "America/New_York"
    ...> }
    iex> Deputy.Locations.create(client, attrs)
    {:ok, %{"Id" => 123}}

# `create_workplace`

```elixir
@spec create_workplace(Deputy.t(), map()) :: {:ok, map()} | {:error, Deputy.Error.t()}
```

Add a new workplace with areas.

## Parameters

- `client`: A Deputy client.
- `attrs`: A map containing the new workplace details.

## Workplace parameters

- `strWorkplaceName`: String naming the workplace.
- `strWorkplaceTimezone`: Timezone for the workplace using TZ database naming.
- `strAddress`: String of the location's address.
- `strLat`: The latitude of the location using a string.
- `strLon`: The longitude of the location using a string.
- `intCountry`: An integer which defines which country the location is in.
- `arrAreaNames`: An array of the area names to add to the location.
- `strWorkplaceCode`: A string with a length of 3 allowing you to define a short code for the location.
- `strPayrollExportCode`: Optional. String naming what to use as a code for payroll exports.
- `blnIsWorkplace`: Boolean (1 - True, 0 - False) whether the location is considered a workplace.
- `blnIsPayrollEntity`: Boolean (1 - True, 0 - False) whether the location has payroll setup.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> attrs = %{
    ...>   strWorkplaceName: "New Workplace",
    ...>   strWorkplaceTimezone: "America/New_York",
    ...>   strAddress: "123 Test St",
    ...>   strLat: "40.7128",
    ...>   strLon: "-74.0060",
    ...>   intCountry: 1,
    ...>   arrAreaNames: ["Reception", "Kitchen"],
    ...>   strWorkplaceCode: "NWP",
    ...>   blnIsWorkplace: 1,
    ...>   blnIsPayrollEntity: 1
    ...> }
    iex> Deputy.Locations.create_workplace(client, attrs)
    {:ok, %{"Id" => 123}}

# `delete`

```elixir
@spec delete(Deputy.t(), integer()) :: {:ok, map()} | {:error, Deputy.Error.t()}
```

Delete a location.

## Parameters

- `client`: A Deputy client.
- `id`: The ID of the location to delete.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.delete(client, 1)
    {:ok, %{"success" => true}}

# `get`

```elixir
@spec get(Deputy.t(), integer()) :: {:ok, map()} | {:error, Deputy.Error.t()}
```

Get location by ID.

## Parameters

- `client`: A Deputy client.
- `id`: The ID of the location to retrieve.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.get(client, 1)
    {:ok, %{"Id" => 1, "CompanyName" => "Test Company"}}

# `get_settings`

```elixir
@spec get_settings(Deputy.t(), integer()) :: {:ok, map()} | {:error, Deputy.Error.t()}
```

Get a location's settings.

## Parameters

- `client`: A Deputy client.
- `id`: The ID of the location to retrieve settings for.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.get_settings(client, 1)
    {:ok, %{"WEEK_START" => 1}}

    # Using the bang version
    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.get_settings!(client, 1)
    %{"WEEK_START" => 1}

    # Error handling
    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> case Deputy.Locations.get_settings(client, 1) do
    ...>   {:ok, settings} -> settings
    ...>   {:error, %Deputy.Error.API{status: 404}} -> "Location not found"
    ...>   {:error, %Deputy.Error.HTTP{reason: reason}} -> "HTTP error: " <> inspect(reason)
    ...> end

# `get_settings!`

```elixir
@spec get_settings!(Deputy.t(), integer()) :: map()
```

Get a location's settings. Raises an exception if the API call returns an error.

## Parameters

- `client`: A Deputy client.
- `id`: The ID of the location to retrieve settings for.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.get_settings!(client, 1)
    %{"WEEK_START" => 1}

# `list`

```elixir
@spec list(Deputy.t()) :: {:ok, [map()]} | {:error, Deputy.Error.t()}
```

Get all locations.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.list(client)
    {:ok, [%{"Id" => 1, "CompanyName" => "Test Company"}]}

    # Using the bang version
    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.list!(client)
    [%{"Id" => 1, "CompanyName" => "Test Company"}]

    # Error handling
    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> case Deputy.Locations.list(client) do
    ...>   {:ok, locations} -> locations
    ...>   {:error, %Deputy.Error.API{status: 403}} -> "Permission denied"
    ...>   {:error, %Deputy.Error.HTTP{reason: reason}} -> "HTTP error: " <> inspect(reason)
    ...> end

# `list!`

```elixir
@spec list!(Deputy.t()) :: [map()]
```

Get all locations. Raises an exception if the API call returns an error.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.list!(client)
    [%{"Id" => 1, "CompanyName" => "Test Company"}]

# `list_simplified`

```elixir
@spec list_simplified(Deputy.t()) :: {:ok, [map()]} | {:error, Deputy.Error.t()}
```

Get a simplified list of locations.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.list_simplified(client)
    {:ok, [%{"Id" => 1, "CompanyName" => "Test Company"}]}

    # Using the bang version
    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.list_simplified!(client)
    [%{"Id" => 1, "CompanyName" => "Test Company"}]

    # Error handling
    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> case Deputy.Locations.list_simplified(client) do
    ...>   {:ok, locations} -> locations
    ...>   {:error, %Deputy.Error.API{status: 403}} -> "Permission denied"
    ...>   {:error, %Deputy.Error.HTTP{reason: reason}} -> "HTTP error: " <> inspect(reason)
    ...> end

# `list_simplified!`

```elixir
@spec list_simplified!(Deputy.t()) :: [map()]
```

Get a simplified list of locations. Raises an exception if the API call returns an error.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.list_simplified!(client)
    [%{"Id" => 1, "CompanyName" => "Test Company"}]

# `update`

```elixir
@spec update(Deputy.t(), integer(), map()) ::
  {:ok, map()} | {:error, Deputy.Error.t()}
```

Update a location.

## Parameters

- `client`: A Deputy client.
- `id`: The ID of the location to update.
- `attrs`: A map containing the fields to update.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.update(client, 1, %{strWorkplaceCode: "UPD"})
    {:ok, %{"success" => true}}

# `update_all_settings`

```elixir
@spec update_all_settings(Deputy.t(), map()) ::
  {:ok, map()} | {:error, Deputy.Error.t()}
```

Modify settings for all locations.

## Parameters

- `client`: A Deputy client.
- `settings`: A map of settings to update.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.update_all_settings(client, %{"WEEK_START" => 2})
    {:ok, %{"success" => true}}

    # Using the bang version
    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.update_all_settings!(client, %{"WEEK_START" => 2})
    %{"success" => true}

    # Error handling
    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> case Deputy.Locations.update_all_settings(client, %{"WEEK_START" => 2}) do
    ...>   {:ok, result} -> "Settings updated"
    ...>   {:error, %Deputy.Error.API{message: message}} -> "API error: " <> message
    ...>   {:error, %Deputy.Error.ValidationError{}} -> "Invalid settings data"
    ...> end

# `update_all_settings!`

```elixir
@spec update_all_settings!(Deputy.t(), map()) :: map()
```

Modify settings for all locations. Raises an exception if the API call returns an error.

## Parameters

- `client`: A Deputy client.
- `settings`: A map of settings to update.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.update_all_settings!(client, %{"WEEK_START" => 2})
    %{"success" => true}

# `update_settings`

```elixir
@spec update_settings(Deputy.t(), integer(), map()) ::
  {:ok, map()} | {:error, Deputy.Error.t()}
```

Modify settings for a single location.

## Parameters

- `client`: A Deputy client.
- `id`: The ID of the location to update settings for.
- `settings`: A map of settings to update.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.update_settings(client, 1, %{"WEEK_START" => 2})
    {:ok, %{"success" => true}}

    # Using the bang version
    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.update_settings!(client, 1, %{"WEEK_START" => 2})
    %{"success" => true}

    # Error handling
    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> case Deputy.Locations.update_settings(client, 1, %{"WEEK_START" => 2}) do
    ...>   {:ok, result} -> "Settings updated"
    ...>   {:error, %Deputy.Error.API{message: message}} -> "API error: " <> message
    ...>   {:error, %Deputy.Error.HTTP{reason: reason}} -> "HTTP error: " <> inspect(reason)
    ...> end

# `update_settings!`

```elixir
@spec update_settings!(Deputy.t(), integer(), map()) :: map()
```

Modify settings for a single location. Raises an exception if the API call returns an error.

## Parameters

- `client`: A Deputy client.
- `id`: The ID of the location to update settings for.
- `settings`: A map of settings to update.

## Examples

    iex> client = Deputy.new(base_url: "https://test.deputy.com", api_key: "test-key")
    iex> Deputy.Locations.update_settings!(client, 1, %{"WEEK_START" => 2})
    %{"success" => true}

---

*Consult [api-reference.md](api-reference.md) for complete listing*