@spec add_passcode(TTlockClient.Types.passcode_add_params()) :: passcode_api_result()

Adds a custom passcode to a lock.

Supports both permanent and temporary passcodes. For temporary passcodes, start_date and end_date must be provided. Maximum 250 passcodes per lock.

Parameters

• params - Passcode add parameters containing all required information

Examples

# Permanent passcode via gateway
params = TTlockClient.Types.new_passcode_add_params(
  lock_id, 123456, "Guest Access", 2, nil, nil, 2
)
{:ok, %{keyboardPwdId: passcode_id}} = TTlockClient.Passcodes.add_passcode(params)

# Temporary passcode (1 week)
start_ms = DateTime.utc_now() |> DateTime.to_unix(:millisecond)
end_ms = DateTime.add(DateTime.utc_now(), 7, :day) |> DateTime.to_unix(:millisecond)

params = TTlockClient.Types.new_passcode_add_params(
  lock_id, 555999, "Week Access", 3, start_ms, end_ms, 2
)
{:ok, result} = TTlockClient.Passcodes.add_passcode(params)

Returns

• {:ok, passcode_add_response} - Success with passcode ID
• {:error, :not_authenticated} - Authentication required
• {:error, %{error_code: -3009}} - Lock passcode storage full (250 max)
• {:error, reason} - API call failed

@spec add_permanent_passcode(integer(), integer(), String.t() | nil) ::
  passcode_api_result()

Convenience function to add a permanent passcode via gateway.

Parameters

• lock_id - The lock ID to add the passcode to
• passcode - The 4-9 digit passcode
• name - Optional name for the passcode

Example

{:ok, result} = TTlockClient.Passcodes.add_permanent_passcode(12345, 123456, "Guest")

@spec add_temporary_passcode(
  integer(),
  integer(),
  DateTime.t() | integer(),
  DateTime.t() | integer(),
  String.t() | nil
) :: passcode_api_result()

Convenience function to add a temporary passcode via gateway.

Parameters

• lock_id - The lock ID to add the passcode to
• passcode - The 4-9 digit passcode
• start_date - Start time (DateTime or milliseconds)
• end_date - End time (DateTime or milliseconds)
• name - Optional name for the passcode

Example

start_time = DateTime.utc_now()
end_time = DateTime.add(start_time, 7, :day)
{:ok, result} = TTlockClient.Passcodes.add_temporary_passcode(
  12345, 987654, start_time, end_time, "Week Access"
)

Helper function to get add type constants.

@spec change_passcode(TTlockClient.Types.passcode_change_params()) ::
  passcode_api_result()

Changes a passcode's name, value, or valid period.

Can change any combination of passcode properties. At least one of the optional parameters must be provided to perform a change.

Parameters

• params - Passcode change parameters containing lock ID, passcode ID, and changes

Examples

# Change passcode name only
params = TTlockClient.Types.new_passcode_change_params(
  12345, 67890, "New Name"
)
{:ok, result} = TTlockClient.Passcodes.change_passcode(params)

# Change passcode value
params = TTlockClient.Types.new_passcode_change_params(
  12345, 67890, nil, 999888
)
{:ok, result} = TTlockClient.Passcodes.change_passcode(params)

# Change validity period
start_ms = DateTime.utc_now() |> DateTime.to_unix(:millisecond)
end_ms = DateTime.add(DateTime.utc_now(), 30, :day) |> DateTime.to_unix(:millisecond)

params = TTlockClient.Types.new_passcode_change_params(
  12345, 67890, nil, nil, start_ms, end_ms
)
{:ok, result} = TTlockClient.Passcodes.change_passcode(params)

Returns

• {:ok, passcode_change_response} - Success with status information
• {:error, :not_authenticated} - Authentication required
• {:error, reason} - API call failed

@spec change_passcode_name(integer(), integer(), String.t()) :: passcode_api_result()

Convenience function to change only a passcode's name.

Parameters

• lock_id - The lock ID containing the passcode
• passcode_id - The passcode ID to change
• new_name - The new name for the passcode

Example

{:ok, result} = TTlockClient.Passcodes.change_passcode_name(12345, 67890, "Updated Name")

@spec change_passcode_period(
  integer(),
  integer(),
  DateTime.t() | integer(),
  DateTime.t() | integer()
) :: passcode_api_result()

Convenience function to change only a passcode's validity period.

Parameters

• lock_id - The lock ID containing the passcode
• passcode_id - The passcode ID to change
• start_date - New start time (DateTime or milliseconds)
• end_date - New end time (DateTime or milliseconds)

Example

start_time = DateTime.utc_now()
end_time = DateTime.add(start_time, 30, :day)
{:ok, result} = TTlockClient.Passcodes.change_passcode_period(12345, 67890, start_time, end_time)

@spec change_passcode_value(integer(), integer(), integer()) :: passcode_api_result()

Convenience function to change only a passcode's value.

Parameters

• lock_id - The lock ID containing the passcode
• passcode_id - The passcode ID to change
• new_passcode - The new passcode value (4-9 digits)

Example

{:ok, result} = TTlockClient.Passcodes.change_passcode_value(12345, 67890, 999888)

Helper function to get change type constants.

@spec delete_passcode(TTlockClient.Types.passcode_delete_params()) ::
  passcode_api_result()

Deletes a passcode from a lock via gateway.

This function deletes passcodes directly via the cloud API for WiFi locks or locks connected to a gateway.

Parameters

• params - Passcode delete parameters containing lock ID and passcode ID

Examples

# Delete via gateway
delete_params = TTlockClient.Types.new_passcode_delete_params(
  12345,  # lock_id
  67890   # passcode_id
)
{:ok, result} = TTlockClient.Passcodes.delete_passcode(delete_params)

Returns

• {:ok, passcode_delete_response} - Success with status information
• {:error, :not_authenticated} - Authentication required
• {:error, reason} - API call failed

@spec delete_passcode_via_gateway(integer(), integer()) :: passcode_api_result()

Convenience function to delete a passcode via gateway.

This is the recommended method for WiFi locks or locks connected to a gateway. The passcode will be deleted directly via the cloud API.

Parameters

• lock_id - The lock ID containing the passcode
• passcode_id - The passcode ID to delete

Example

{:ok, result} = TTlockClient.Passcodes.delete_passcode_via_gateway(12345, 67890)

@spec get_lock_passcodes(integer(), String.t() | nil) :: passcode_api_result()

Convenience function to get all passcodes for a lock.

Parameters

• lock_id - The lock ID to get passcodes for
• search_str - Optional search string

Example

{:ok, %{list: passcodes}} = TTlockClient.Passcodes.get_lock_passcodes(12345)

@spec get_passcode_list(TTlockClient.Types.passcode_list_params()) ::
  passcode_api_result()

Retrieves all passcodes created for a lock.

Returns both random and custom passcodes with pagination support.

Parameters

• params - Passcode list parameters containing lock ID and optional filters

Examples

# Get first page of passcodes for a lock
params = TTlockClient.Types.new_passcode_list_params(lock_id)
{:ok, response} = TTlockClient.Passcodes.get_passcode_list(params)

# Search for specific passcodes
params = TTlockClient.Types.new_passcode_list_params(lock_id, "Guest", 1, 50, 1)
{:ok, response} = TTlockClient.Passcodes.get_passcode_list(params)

# Access the results
%{list: passcodes, total: total_count} = response

Returns

• {:ok, passcode_list_response} - Success with passcode list data
• {:error, :not_authenticated} - Authentication required
• {:error, reason} - API call failed

Helper function to get order by constants.

Helper function to get passcode type constants.

@spec search_passcodes(integer(), String.t()) :: passcode_api_result()

Convenience function to search passcodes by name or passcode value.

Parameters

• lock_id - The lock ID to search in
• search_term - Search term (name or exact passcode match)

Example

{:ok, results} = TTlockClient.Passcodes.search_passcodes(12345, "Guest")