# এক্সচেঞ্জ রেট API ইন্টিগ্রেশন গাইড

## ভূমিকা

বর্তমানে প্লাগিনে স্ট্যাটিক এক্সচেঞ্জ রেট ব্যবহার করা হচ্ছে যা `BIZZMUDRA_Exchange_Rate` ক্লাসে JSON ফরম্যাটে সংরক্ষিত আছে। ভবিষ্যতে রিয়েল-টাইম এক্সচেঞ্জ রেট পেতে এক্সটার্নাল API ইন্টিগ্রেট করা যেতে পারে।

---

## জনপ্রিয় এক্সচেঞ্জ রেট API সার্ভিসসমূহ

### ১। Open Exchange Rates
**ওয়েবসাইট:** https://openexchangerates.org

**বৈশিষ্ট্য:**
- ১৭০+ কারেন্সি সাপোর্ট
- ফ্রি টায়ারে ১,০০০ রিকোয়েস্ট/মাস
- USD বেস কারেন্সি (ফ্রি প্ল্যানে)
- JSON রেসপন্স

**এন্ডপয়েন্ট উদাহরণ:**
```
GET https://openexchangerates.org/api/latest.json?app_id=YOUR_APP_ID
```

**রেসপন্স স্ট্রাকচার:**
```json
{
  "base": "USD",
  "rates": {
    "EUR": 0.85,
    "GBP": 0.74,
    "BDT": 122.42
  }
}
```

---

### ২। ExchangeRate-API
**ওয়েবসাইট:** https://exchangerate-api.com

**বৈশিষ্ট্য:**
- ১৬০+ কারেন্সি সাপোর্ট
- ফ্রি টায়ারে ১,৫০০ রিকোয়েস্ট/মাস
- যেকোনো বেস কারেন্সি সাপোর্ট
- সহজ ইন্টিগ্রেশন

**এন্ডপয়েন্ট উদাহরণ:**
```
GET https://v6.exchangerate-api.com/v6/YOUR_API_KEY/latest/USD
```

---

### ৩। Fixer.io
**ওয়েবসাইট:** https://fixer.io

**বৈশিষ্ট্য:**
- ১৭০+ কারেন্সি সাপোর্ট
- ফ্রি টায়ারে ১০০ রিকোয়েস্ট/মাস
- হিস্টোরিক্যাল ডাটা সাপোর্ট
- ফ্লাকচুয়েশন এন্ডপয়েন্ট

**এন্ডপয়েন্ট উদাহরণ:**
```
GET https://data.fixer.io/api/latest?access_key=YOUR_API_KEY
```

---

### ৪। CurrencyLayer
**ওয়েবসাইট:** https://currencylayer.com

**বৈশিষ্ট্য:**
- ১৬৮ কারেন্সি সাপোর্ট
- রিয়েল-টাইম আপডেট
- সোর্স কারেন্সি স্যুইচিং
- JSON ও XML সাপোর্ট

---

## প্রস্তাবিত ইমপ্লিমেন্টেশন

### ধাপ ১: API কনফিগারেশন সেটিংস

সেটিংস পেজে নতুন সেকশন যোগ করা:

```php
// API Settings Section
array(
    'id'          => 'api_settings',
    'title'       => __( 'API Settings', 'bizzmudra' ),
    'description' => __( 'Configure exchange rate API settings.', 'bizzmudra' ),
    'fields'      => array(
        array(
            'id'          => 'api_provider',
            'type'        => 'select',
            'title'       => __( 'API Provider', 'bizzmudra' ),
            'options'     => array(
                'none'               => __( 'None (Use Static Rates)', 'bizzmudra' ),
                'openexchangerates'  => __( 'Open Exchange Rates', 'bizzmudra' ),
                'exchangerate_api'   => __( 'ExchangeRate-API', 'bizzmudra' ),
                'fixer'              => __( 'Fixer.io', 'bizzmudra' ),
            ),
            'default'     => 'none',
        ),
        array(
            'id'          => 'api_key',
            'type'        => 'text',
            'title'       => __( 'API Key', 'bizzmudra' ),
            'description' => __( 'Enter your API key from the selected provider.', 'bizzmudra' ),
        ),
        array(
            'id'          => 'update_frequency',
            'type'        => 'select',
            'title'       => __( 'Update Frequency', 'bizzmudra' ),
            'options'     => array(
                'hourly'  => __( 'Hourly', 'bizzmudra' ),
                'daily'   => __( 'Daily', 'bizzmudra' ),
                'weekly'  => __( 'Weekly', 'bizzmudra' ),
            ),
            'default'     => 'daily',
        ),
    ),
)
```

---

### ধাপ ২: API ফেচ মেথড

`BIZZMUDRA_Exchange_Rate` ক্লাসে নতুন মেথড:

```php
/**
 * Fetch exchange rates from external API
 *
 * @return array|WP_Error Exchange rates or error
 */
public function fetch_exchange_rates_from_api() {
    $settings = get_option( 'bizzmudra_settings', array() );
    $provider = isset( $settings['api_provider'] ) ? $settings['api_provider'] : 'none';
    $api_key  = isset( $settings['api_key'] ) ? $settings['api_key'] : '';
    
    if ( 'none' === $provider || empty( $api_key ) ) {
        return $this->get_default_exchange_rates();
    }
    
    $api_url = $this->get_api_url( $provider, $api_key );
    
    $response = wp_remote_get( $api_url, array(
        'timeout' => 15,
        'headers' => array(
            'Accept' => 'application/json',
        ),
    ) );
    
    if ( is_wp_error( $response ) ) {
        return $response;
    }
    
    $body = wp_remote_retrieve_body( $response );
    $data = json_decode( $body, true );
    
    if ( ! isset( $data['rates'] ) ) {
        return new WP_Error( 'invalid_response', __( 'Invalid API response', 'bizzmudra' ) );
    }
    
    // Store in transient and return
    $this->store_rates_in_transient( $data['rates'] );
    return $data['rates'];
}

/**
 * Get API URL based on provider
 *
 * @param string $provider API provider name
 * @param string $api_key  API key
 * @return string API URL
 */
private function get_api_url( $provider, $api_key ) {
    switch ( $provider ) {
        case 'openexchangerates':
            return "https://openexchangerates.org/api/latest.json?app_id={$api_key}";
        
        case 'exchangerate_api':
            return "https://v6.exchangerate-api.com/v6/{$api_key}/latest/USD";
        
        case 'fixer':
            return "https://data.fixer.io/api/latest?access_key={$api_key}";
        
        default:
            return '';
    }
}
```

---

### ধাপ ৩: ক্রন জব সেটআপ

অটোমেটিক রেট আপডেটের জন্য:

```php
/**
 * Schedule exchange rate update cron job
 */
public function schedule_rate_update() {
    if ( ! wp_next_scheduled( 'bizzmudra_update_exchange_rates' ) ) {
        $settings  = get_option( 'bizzmudra_settings', array() );
        $frequency = isset( $settings['update_frequency'] ) ? $settings['update_frequency'] : 'daily';
        
        wp_schedule_event( time(), $frequency, 'bizzmudra_update_exchange_rates' );
    }
}

/**
 * Cron callback to update exchange rates
 */
public function cron_update_exchange_rates() {
    $this->fetch_exchange_rates_from_api();
}

// Hook setup in constructor:
add_action( 'bizzmudra_update_exchange_rates', array( $this, 'cron_update_exchange_rates' ) );
```

---

### ধাপ ৪: ম্যানুয়াল রিফ্রেশ বাটন

অ্যাডমিন প্যানেলে রিফ্রেশ বাটন:

```php
array(
    'id'      => 'refresh_rates',
    'type'    => 'html',
    'title'   => __( 'Refresh Rates', 'bizzmudra' ),
    'content' => '<button type="button" class="button button-primary" id="bizzmudra-refresh-rates">' 
                 . __( 'Fetch Latest Rates', 'bizzmudra' ) 
                 . '</button>
                 <span id="bizzmudra-refresh-status"></span>',
),
```

---

## এরর হ্যান্ডলিং

```php
/**
 * Handle API errors gracefully
 *
 * @param WP_Error $error API error
 * @return void
 */
private function handle_api_error( $error ) {
    // Log error
    if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
        error_log( 'Bizzmudra API Error: ' . $error->get_error_message() );
    }
    
    // Send admin notification (optional)
    $admin_email = get_option( 'admin_email' );
    wp_mail(
        $admin_email,
        __( 'Bizzmudra: Exchange Rate Update Failed', 'bizzmudra' ),
        sprintf(
            __( 'Failed to fetch exchange rates. Error: %s', 'bizzmudra' ),
            $error->get_error_message()
        )
    );
    
    // Fallback to cached rates
    return $this->get_default_exchange_rates();
}
```

---

## সিকিউরিটি বিবেচনা

### ১। API Key সংরক্ষণ
- API key এনক্রিপ্ট করে সংরক্ষণ করা উচিত
- ডাটাবেসে প্লেইন টেক্সটে রাখা অনুচিত

### ২। রেট লিমিটিং
- API কল রেট লিমিট মনিটর করা
- ক্যাশিং দিয়ে অপ্রয়োজনীয় কল কমানো

### ৩। Transient ব্যবহার
- API ফেইল হলেও ক্যাশড ডাটা ব্যবহার করা
- গ্রেসফুল ফলব্যাক নিশ্চিত করা

---

## খরচ তুলনা

| সার্ভিস | ফ্রি রিকোয়েস্ট | পেইড প্ল্যান শুরু |
|---------|----------------|-------------------|
| Open Exchange Rates | ১,০০০/মাস | $12/মাস |
| ExchangeRate-API | ১,৫০০/মাস | $9.99/মাস |
| Fixer.io | ১০০/মাস | $14.99/মাস |
| CurrencyLayer | ২৫০/মাস | $14.99/মাস |

---

## সুপারিশ

ছোট থেকে মাঝারি সাইটের জন্য **ExchangeRate-API** সবচেয়ে ভালো অপশন:
- বেশি ফ্রি রিকোয়েস্ট
- সহজ ইন্টিগ্রেশন
- যেকোনো বেস কারেন্সি সাপোর্ট
- কম খরচের পেইড প্ল্যান

---

**ডকুমেন্ট লেখক:** GitHub Copilot  
**তারিখ:** ২২ জানুয়ারি, ২০২৬