HipcallSMS.Adapters.Iletimerkezi (HipcallSMS v0.3.0)

View Source

An adapter for Iletimerkezi SMS API.

This adapter provides SMS delivery through Iletimerkezi's REST API, which is a popular SMS service provider in Turkey. It supports scheduled messaging and IYS (İzinli Yollama Sistemi) compliance for Turkish regulations.

For reference: Iletimerkezi API docs

Configuration

The Iletimerkezi adapter requires the following configuration:

  • :key - Your Iletimerkezi API key
  • :hash - Your Iletimerkezi API hash

Configuration Examples

# In config/config.exs
config :hipcall_sms,
  adapter: HipcallSMS.Adapters.Iletimerkezi,
  iletimerkezi_key: {:system, "ILETIMERKEZI_KEY"},
  iletimerkezi_hash: {:system, "ILETIMERKEZI_HASH"}

# Runtime configuration override
config = [
  adapter: HipcallSMS.Adapters.Iletimerkezi,
  key: "your_api_key",
  hash: "your_api_hash"
]

Provider Options

The Iletimerkezi adapter supports the following provider-specific options via provider_options:

  • :send_date_time - Schedule message for future delivery (array format)
  • :iys - IYS compliance setting (default: "1")
  • :iys_list - IYS list type (default: "BIREYSEL")

Examples

# Basic SMS
sms = SMS.new(from: "SENDER", to: "+905551234567", text: "Merhaba!")
{:ok, response} = HipcallSMS.deliver(sms)

# Scheduled SMS
sms =
  SMS.new(from: "SENDER", to: "+905551234567", text: "Hatırlatma!")
  |> SMS.put_provider_option(:send_date_time, ["2024", "12", "25", "10", "30"])

# SMS with custom IYS settings
sms =
  SMS.new(from: "SENDER", to: "+905551234567", text: "Bilgilendirme")
  |> SMS.put_provider_option(:iys, "1")
  |> SMS.put_provider_option(:iys_list, "TACIR")

Summary

Functions

Delivers an SMS through Iletimerkezi's REST API.

Gets the account balance from Iletimerkezi's REST API.

Functions

deliver(sms, config \\ [])

@spec deliver(HipcallSMS.SMS.t(), Keyword.t()) :: {:ok, map()} | {:error, map()}

Delivers an SMS through Iletimerkezi's REST API.

This function sends an SMS message using Iletimerkezi's JSON API. It handles authentication, request formatting, and response parsing with IYS compliance.

Parameters

  • sms - The SMS struct containing message details
  • config - Configuration keyword list (optional, defaults to application config)

Returns

  • {:ok, response} - Success with Iletimerkezi API response
  • {:error, reason} - Failure with error details including HTTP status and body

Response Format

Success responses contain the raw Iletimerkezi API response:

{:ok, %{
  "response" => %{
    "status" => %{
      "code" => "200",
      "message" => "OK"
    },
    "order" => %{
      "id" => "order_id"
    }
  }
}}

Examples

# Basic delivery
sms = SMS.new(from: "SENDER", to: "+905551234567", text: "Merhaba!")
{:ok, response} = deliver(sms)

# Delivery with custom config
config = [key: "custom_key", hash: "custom_hash"]
{:ok, response} = deliver(sms, config)

get_balance(config \\ [])

@spec get_balance(Keyword.t()) :: {:ok, map()} | {:error, map()}

Gets the account balance from Iletimerkezi's REST API.

This function retrieves the current account balance using Iletimerkezi's Balance API. It handles authentication and response parsing.

Parameters

  • config - Configuration keyword list (optional, defaults to application config)

Returns

  • {:ok, balance_info} - Success with balance information
  • {:error, reason} - Failure with error details including HTTP status and body

Response Format

Success responses contain normalized balance information:

%{
  balance: "300.00",           # Current account balance (TL)
  sms_balance: "18343",        # SMS credit balance
  currency: "TRY",             # Currency (Turkish Lira)
  provider: "iletimerkezi",    # Provider identifier
  provider_response: %{}       # Full Iletimerkezi API response
}

Examples

# Get balance with application config
{:ok, balance} = get_balance()

# Get balance with custom config
config = [key: "custom_key", hash: "custom_hash"]
{:ok, balance} = get_balance(config)

get_config_value(key, default)

Callback implementation for HipcallSMS.Adapter.get_config_value/2.

validate_config(config)

Callback implementation for HipcallSMS.Adapter.validate_config/1.

validate_dependency()

Callback implementation for HipcallSMS.Adapter.validate_dependency/0.