مستندات API v1 پایدار v2 جدید

۱. مقدمه

این API فقط برای دریافت قیمت طلا، ارز، فلزات/سکه و رمزارز است. endpointهای داده نیاز به توکن API دارند. توکن را از صفحه عضویت بگیرید و در پنل مدیریت کنید.

قیمت‌ها از دادهٔ ذخیره‌شده در سایت با تأخیر کوتاه هستند و جنبه اطلاعاتی دارند. این سرویس ارسال پیامک عمومی ارائه نمی‌دهد.

۲. دو شکل URL (هر دو معتبر و پایدار)

اگر rewrite روی هاست فعال باشد می‌توانید از مسیر تمیز استفاده کنید؛ در غیر این صورت همیشه از api_v1.php?r= استفاده کنید.

مقدار r بدون اسلش ابتدایی است، مثلاً: gold/current ، fx ، metals ، fx/show.

۳. احراز هویت و توکن

یکی از روش‌های زیر کافی است:

• هدر: X-Api-Token: YOUR_TOKEN (پیشنهادی)
• هدر: Authorization: Bearer YOUR_TOKEN
• پارامتر: ?api_token=YOUR_TOKEN

۴. پوسته استاندارد پاسخ

{
  "ok": true,
  "message": "OK",
  "data": { },
  "meta": { }
}

ok موفقیت منطقی، data بدنهٔ اصلی، meta اطلاعات جانبی (ممکن است خالی باشد یا فیلدهای کمکی داشته باشد).

۶. فهرست رسمی Endpointهای قیمت (v1)

کدهای metals

• geram18 — گرم طلای ۱۸ عیار (تومان)
• abshode — طلای آبشده / مثقال (تومان)
• seke_emami ، seke_bahar ، seke_nim ، seke_rob ، seke_grami
• ounce — انس جهانی طلا (دلار)
• ounce_silver — انس نقره (دلار)

کدهای fx (نمونه)

USD, EUR, GBP, AED, TRY, CNY, CAD, AUD, CHF, JPY, SAR, QAR, KWD, OMR, IQD, RUB, AZN, GEL, AFN, PKR

۷. مستندات فیلدهای داخل data

۷.۱ gold/current

۷.۲ fx

۷.۳ metals

۸. نمونه JSON واقعی (ساختاری — اعداد نمونه)

۸.۱ gold/current

{
  "ok": true,
  "message": "OK",
  "data": {
    "ok": true,
    "current": 15720000,
    "ts": 1727440000,
    "today": {
      "date": "2026-09-27",
      "date_jalali": "1405/07/05",
      "open": 15680000,
      "high": 15750000,
      "low": 15650000,
      "close": 15720000
    },
    "yesterday": {
      "date": "2026-09-26",
      "date_jalali": "1405/07/04",
      "close": 15690000
    }
  },
  "meta": {}
}

۸.۲ fx

{
  "ok": true,
  "message": "OK",
  "data": {
    "items": [
      {
        "code": "USD",
        "name": "دلار آمریکا",
        "flag": "🇺🇸",
        "buy": 221750,
        "sell": 224000,
        "delta": 250,
        "ts": 1727440000,
        "time_jalali": "1405/07/05 12:30"
      },
      {
        "code": "EUR",
        "name": "یورو",
        "flag": "🇪🇺",
        "buy": 240000,
        "sell": 242500,
        "delta": null,
        "ts": 1727440000,
        "time_jalali": "1405/07/05 12:30"
      }
    ],
    "last_ts": 1727440000,
    "last_jalali": "1405/07/05 12:30"
  },
  "meta": {}
}

۸.۳ metals

{
  "ok": true,
  "message": "OK",
  "data": {
    "items": [
      {
        "code": "geram18",
        "name": "گرم طلای ۱۸ عیار",
        "unit": "تومان",
        "icon": "🥇",
        "price": 15720000,
        "real_price": 15500000,
        "bubble_pct": 1.42,
        "change_pct": 0.35,
        "ts": 1727440100,
        "time": "2026-09-27T12:31:40+03:30",
        "time_jalali": "1405/07/05 12:31"
      },
      {
        "code": "ounce",
        "name": "انس جهانی طلا",
        "unit": "دلار",
        "icon": "🌍",
        "price": 2650.5,
        "real_price": null,
        "bubble_pct": null,
        "change_pct": null,
        "ts": 1727440100,
        "time": "2026-09-27T12:31:40+03:30",
        "time_jalali": "1405/07/05 12:31"
      }
    ]
  },
  "meta": { "table": "metal_ticks" }
}

۹. نمونه کد (چند زبان)

در همهٔ نمونه‌ها YOUR_TOKEN را با توکن پنل عوض کنید. Base پیشنهادی: https://24tala.ir/api_v1.php?r=...

۹.۱ cURL

curl -s -H "X-Api-Token: YOUR_TOKEN" \
  "https://24tala.ir/api_v1.php?r=gold/current"

curl -s -H "X-Api-Token: YOUR_TOKEN" \
  "https://24tala.ir/api_v1.php?r=fx"

curl -s -H "X-Api-Token: YOUR_TOKEN" \
  "https://24tala.ir/api_v1.php?r=metals"

۹.۲ PHP

<?php
$token = 'YOUR_TOKEN';
$url = 'https://24tala.ir/api_v1.php?r=gold/current';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-Api-Token: ' . $token,
    ],
    CURLOPT_TIMEOUT => 15,
]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode((string)$body, true);
if ($code === 200 && !empty($data['ok'])) {
    echo 'قیمت طلا: ' . ($data['data']['current'] ?? '—');
} else {
    echo 'خطا: ' . ($data['message'] ?? $body);
}

۹.۳ JavaScript (fetch — مرورگر یا Node 18+)

const token = 'YOUR_TOKEN';
const url = 'https://24tala.ir/api_v1.php?r=fx';

const res = await fetch(url, {
  headers: {
    'Accept': 'application/json',
    'X-Api-Token': token,
  },
});
const json = await res.json();
if (json.ok) {
  const usd = json.data.items.find(i => i.code === 'USD');
  console.log('USD sell:', usd?.sell, 'ts:', usd?.ts);
} else {
  console.error(json.message);
}

۹.۴ Python 3

import requests

token = "YOUR_TOKEN"
url = "https://24tala.ir/api_v1.php?r=metals"
r = requests.get(url, headers={"X-Api-Token": token, "Accept": "application/json"}, timeout=15)
r.raise_for_status()
payload = r.json()
if payload.get("ok"):
    for row in payload["data"]["items"]:
        print(row["code"], row["price"], row.get("unit"), row.get("ts"))
else:
    print("error:", payload.get("message"))

۹.۵ C# (HttpClient)

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;

var token = "YOUR_TOKEN";
var url = "https://24tala.ir/api_v1.php?r=gold/current";

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Token", token);
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var json = await client.GetStringAsync(url);
using var doc = JsonDocument.Parse(json);
var root = doc.RootElement;
if (root.GetProperty("ok").GetBoolean())
{
    var current = root.GetProperty("data").GetProperty("current");
    Console.WriteLine($"Gold: {current}");
}

۹.۶ Go

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://24tala.ir/api_v1.php?r=fx", nil)
	req.Header.Set("X-Api-Token", "YOUR_TOKEN")
	req.Header.Set("Accept", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	var payload map[string]any
	_ = json.Unmarshal(body, &payload)
	fmt.Println(payload["ok"], payload["data"])
}

۹.۷ Java (HttpClient — Java 11+)

import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://24tala.ir/api_v1.php?r=metals"))
    .header("X-Api-Token", "YOUR_TOKEN")
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());

۱۰. کدهای خطا

۱۲. Changelog مستندات

• 2026-10-01 — v2.9.0: معرفی API v2 با جداول مجزا، endpoint /rates سازگار با ویجت، Rate Limit، لاگ IP/Origin، فعال/غیرفعال‌سازی نمادها و پنل ادمین admin_api_v2.php. v1 بدون تغییر.
• 2026-09-27 — docs 2.8: جدول فیلدهای data برای gold/current، fx، metals؛ نگاشت قیمت لحظه‌ای؛ دو شکل URL؛ نمونه JSON؛ نمونه کد PHP / JS / Python / C# / Go / Java؛ سیاست پایداری v1.
• v1 API: قرارداد اجرایی وب‌سرویس‌های موجود بدون تغییر عمدی رفتار؛ این به‌روزرسانی عمدتاً مستندات است.

۱۳. نکات نهایی

• توکن را محرمانه نگه دارید؛ در فرانت عمومی یا مخزن عمومی commit نکنید.
• برای کشف صفحات سایت توسط مدل‌های زبانی: llm.txt و llm.md
• سایت‌مپ قیمت‌ها: sitemap-prices.xml