مستندات مقدماتی API.TALA.IR

معرفی

API.TALA.IR برای دریافت داده های ساختاریافته بازار طراحی شده است. خروجی سرویس ها به صورت JSON ارائه می شود و برای استفاده در سایت ها، اپلیکیشن ها، سامانه های حسابداری، تابلوهای نرخ و پنل های سازمانی مناسب است.

شروع سریع

1. کلید API اختصاصی خود را از پنل دریافت کنید.
2. درخواست را به endpoint مورد نظر ارسال کنید.
3. هدر x-api-key را همراه درخواست بفرستید.
4. پاسخ JSON را در نرم افزار خود پردازش کنید.

احراز هویت

تمام درخواست ها باید کلید دسترسی معتبر داشته باشند. کلید از طریق هدر زیر ارسال می شود:

x-api-key: YOUR_API_KEY

در نسخه نهایی مستندات، قوانین امنیتی، محدودیت دامنه، نحوه تعویض کلید و سیاست نگهداری کلیدها تکمیل می شود.

Endpoint های اولیه

ساختار پاسخ نمونه

نمونه پاسخ زیر قالب فهرست رفرنس های فعال است و قیمت لحظه ای در این endpoint نمایش داده نمی شود:

{
  "success": true,
  "generated_at": "2026-07-11T20:31:00+04:00",
    "references": [
    {
      "key": "gold18",
      "title": "طلا ۱۸ عیار",
            "description": "طلا ۱۸ عیار",
            "unit": "تومان",
            "source_key": "gold18",
            "aliases": "gold18,geram18,18ayar,gold_18",
            "status": "active"
    }
  ]
}

برای دریافت قیمت، کلیدهای مورد نظر را در مسیر جزئیات ارسال کنید:

GET /v1/rates/gold18,usd,eur

{
    "success": true,
    "generated_at": "2026-07-11T20:31:00+04:00",
    "count": 3,
    "rates": [
        {
            "key": "gold18",
            "title": "طلا ۱۸ عیار",
            "value": 7600000,
            "unit": "تومان",
            "source_key": "gold18",
            "updated_at": "2026-07-11T20:30:42+04:00",
            "status": "ok"
        }
    ],
    "meta": {
        "max_keys": 10,
        "includes_prices": true
    }
}

نمونه کدها

• PHP
• cURL
• Python
• C#

• <?php
  $ch = curl_init('https://api.tala.ir/v1/rates/gold18,usd,eur');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ['x-api-key: YOUR_API_KEY'],
      CURLOPT_TIMEOUT => 15,
  ]);
  $response = curl_exec($ch);
  curl_close($ch);
  $data = json_decode($response, true);
  print_r($data);

• # فهرست رفرنس های فعال، بدون قیمت
  curl -s 'https://api.tala.ir/v1/rates' \
      -H 'x-api-key: YOUR_API_KEY'
  
  # جزئیات همراه قیمت، حداکثر ۱۰ کلید
  curl -s 'https://api.tala.ir/v1/rates/gold18,usd,eur' \
      -H 'x-api-key: YOUR_API_KEY'

• import requests
  
  response = requests.get(
      'https://api.tala.ir/v1/rates/gold18,usd,eur',
      headers={'x-api-key': 'YOUR_API_KEY'},
      timeout=15
  )
  print(response.json())

• using System.Net.Http;
  using System.Text.Json;
  using System.Text.Json.Serialization;
  
  using var client = new HttpClient
  {
      Timeout = TimeSpan.FromSeconds(15)
  };
  
  client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
  
  var url = "https://api.tala.ir/v1/rates/gold18,usd,eur";
  using var response = await client.GetAsync(url);
  var json = await response.Content.ReadAsStringAsync();
  
  if (!response.IsSuccessStatusCode)
  {
      throw new Exception($"API request failed: {(int)response.StatusCode} - {json}");
  }
  
  var options = new JsonSerializerOptions
  {
      PropertyNameCaseInsensitive = true
  };
  
  var result = JsonSerializer.Deserialize<TalaRatesResponse>(json, options);
  if (result == null || !result.Success)
  {
      throw new Exception($"API error: {result?.Error ?? "UNKNOWN_ERROR"}");
  }
  
  foreach (var rate in result.Rates)
  {
      Console.WriteLine($"{rate.Key}: {rate.Value:N0} {rate.Unit} ({rate.Title})");
  }
  
  public sealed record TalaRatesResponse(
      bool Success,
      string Status,
      string? Error,
      int Count,
      List<TalaRate> Rates
  );
  
  public sealed record TalaRate(
      string Key,
      string Title,
      decimal? Value,
      string Unit,
      [property: JsonPropertyName("updated_at")] string UpdatedAt,
      string Status
  );

استفاده در WordPress

در وردپرس بهتر است درخواست API داخل افزونه اختصاصی یا فایل functions.php قالب قرار بگیرد و کلید API در تنظیمات امن سایت نگهداری شود. نمونه زیر با wp_remote_get نرخ چند رفرنس را می گیرد و یک shortcode ساده می سازد.

add_shortcode('tala_rates', function () {
    $api_key = 'YOUR_API_KEY';
    $url = 'https://api.tala.ir/v1/rates/gold18,usd,eur';

    $response = wp_remote_get($url, [
        'timeout' => 15,
        'headers' => [
            'x-api-key' => $api_key,
        ],
    ]);

    if (is_wp_error($response)) {
        return 'خطا در دریافت اطلاعات';
    }

    $body = wp_remote_retrieve_body($response);
    $data = json_decode($body, true);

    if (empty($data['success']) || empty($data['rates'])) {
        return 'اطلاعاتی برای نمایش وجود ندارد';
    }

    $html = '<ul class="tala-rates">';
    foreach ($data['rates'] as $rate) {
        $title = esc_html($rate['title']);
        $value = esc_html(number_format((float)$rate['value']));
        $unit = esc_html($rate['unit']);
        $html .= "<li>{$title}: {$value} {$unit}</li>";
    }
    $html .= '</ul>';

    return $html;
});

خطاهای رایج