Hamta İş Ortağı Kur API'si

Genel bakış

Hamta API'si, yanıtı UTF-8 kodlu JSON olarak döndüren salt okunur bir REST hizmetidir. Her API anahtarı tek bir iş ortağı hesabına aittir ve yalnızca o hesabın kurlarını döndürür: Hamta'dan maliyetiniz ve iş ortağı panelinde kendi belirlediğiniz marjla müşteri fiyatınız. Piyasa referans kurları bu API'de sunulmaz.

Kimlik doğrulama

Her istek, API anahtarını Authorization başlığında Bearer olarak göndermelidir. Anahtarlar hamta_live_ önekiyle başlar.

1. İş ortağı paneline giriş yapın ve “API ve Telegram” sayfasını açın.
2. Yeni bir anahtar oluşturun (Sahip, Yönetici ve Geliştirici rolleri anahtar oluşturabilir).
3. Anahtar yalnızca bir kez gösterilir: sunucunuzda güvenli bir ortam değişkeninde saklayın. Hamta yalnızca anahtarın şifrelenmiş (hash) kopyasını tutar; anahtarı kaybederseniz iptal edip yenisini oluşturun.

Authorization: Bearer hamta_live_…

API anahtarını asla tarayıcı tarafı koda (sayfa JavaScript'i), mobil uygulamaya veya herkese açık bir kod deposuna koymayın. İstekleri yalnızca sunucunuzdan gönderin.

Kurları al

İş ortağı hesabınızdaki tüm enstrümanların güncel kurlarını döndürür. İstek parametre veya gövde almaz ve yanıt hiçbir zaman önbelleğe alınmaz (Cache-Control: no-store).

Saatler ve erişim

Kur API'si piyasa günlerinde Tahran saatiyle 11:00–20:00 arasında yanıt verir (kabul edilen son istek 19:59'da). Cuma günleri ve resmî piyasa tatillerinde kapalıdır. Bu saatlerin dışında OUTSIDE_MARKET_HOURS koduyla 503 döner; Retry-After başlığı bir sonraki açılışa kalan saniyeyi, next_open alanı ise açılış zamanını (ISO 8601, UTC) verir.

{
  "ok": false,
  "success": false,
  "error": "OUTSIDE_MARKET_HOURS",
  "message": "<string>",
  "market_hours": "11:00 - 20:00 Asia/Tehran",
  "next_open": "<ISO 8601 string>"
}

İzinli IP listesi isteğe bağlıdır ve talebiniz üzerine Hamta desteği tarafından tanımlanır. Hiçbir adres kayıtlı olmadığı sürece anahtarlarınız her IP'den kabul edilir. Bir veya daha fazla adres kaydedildiğinde, başka bir adresten gelen her istek 403 ve IP_NOT_ALLOWED koduyla reddedilir. Yalnızca tam ve herkese açık IPv4 veya IPv6 adresleri kabul edilir (aralık kabul edilmez), en fazla 10 adet; liste hesabınızın tüm anahtarları için geçerlidir ve iş ortağı panelinde (API ve Telegram bölümü) görüntülenir.

{
  "ok": false,
  "success": false,
  "error": "IP_NOT_ALLOWED",
  "message": "<string>"
}

Yanıt

Başarılı yanıt 200 durum koduyla döner. Aşağıdaki yapı, API'nin döndürdüğü anahtarların tam aynısıdır; sayısal değerlerin yerine veri tipi yazılmıştır. Kendi hesabınızın gerçek yanıtını görmek için iş ortağı panelindeki “API ve Telegram” sayfasına bakın.

{
  "ok": true,
  "partner": "<string>",
  "updatedAt": "<ISO 8601 string | null>",
  "note": "buy = customer buys (خرید از ما), sell = customer sells (فروش به ما). null = not configured.",
  "rates": [
    {
      "code": "havaleLir",
      "label": "لیر حواله ترکیه",
      "unit": "TOMAN",
      "unitBasis": 1,
      "partnerCost": {
        "retail": {
          "buy": "<decimal string | null>",
          "sell": "<decimal string | null>"
        },
        "wholesale": {
          "buy": "<decimal string | null>",
          "sell": "<decimal string | null>"
        }
      },
      "customerPrice": {
        "retail": {
          "buy": "<decimal string | null>",
          "sell": "<decimal string | null>"
        },
        "wholesale": {
          "buy": "<decimal string | null>",
          "sell": "<decimal string | null>"
        }
      }
    },
    …
  ]
}

Alanlar

Tüm fiyatlar ondalık sayı dizesi (en fazla 6 ondalık basamak) veya null'dır. null “ayarlanmadı” demektir; asla sıfır olarak değerlendirmeyin.

Enstrümanlar

rates listesi her zaman bu enstrümanları bu sırayla içerir:

Hatalar

API hataları "ok": false ve "error" alanında bir kodla JSON olarak döner. IP_NOT_ALLOWED ve OUTSIDE_MARKET_HOURS ayrıca "success": false ve Accept-Language başlığınızın dilinde bir "message" içerir (fa, en, tr, hy; aksi hâlde İngilizce). Tablonun son iki satırı sitenin güvenlik katmanından gelir ve JSON değil düz metindir.

Sınırlar

• API anahtarı başına dakikada en fazla 60 istek.
• İstekler yalnızca piyasa günlerinde, Tahran saatiyle 11:00–20:00 arasında yanıtlanır (bkz. Saatler ve erişim).
• İzinli IP listesi nedeniyle reddedilen istekler anahtarınızın dakikalık sınırından düşülmez.
• Ayrıca her IP adresinin site genelinde ayrı bir istek sınırı vardır (sürekli olarak saniyede en fazla yaklaşık 2 istek).
• Yalnızca GET yöntemi desteklenir.

Kullanıma hazır kod örnekleri

Aşağıdaki örnekler anahtarı HAMTA_API_KEY ortam değişkeninden okur, hataları kontrol eder ve her enstrümanın perakende müşteri fiyatını yazdırır. PHP örneği WooCommerce veya Laravel gibi e-ticaret mağazalarına uygundur.

<?php
// Server side only: never send the API key to the browser.
$apiKey = getenv('HAMTA_API_KEY'); // hamta_live_...

$ch = curl_init('https://hamtagift.com/api/partner/v1/rates');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey, 'Accept: application/json'],
    CURLOPT_TIMEOUT        => 10,
]);
$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$error  = curl_error($ch);
curl_close($ch);

if ($body === false) {
    throw new RuntimeException('Hamta API unreachable: ' . $error);
}
$data = json_decode($body, true); // null for the plain-text 403/429 of the security layer
if ($status !== 200 || !is_array($data) || empty($data['ok'])) {
    // 401: check the key. 429: wait for Retry-After. 503: keep your last good prices.
    throw new RuntimeException('Hamta API error: ' . ($data['error'] ?? ('HTTP ' . $status)));
}

foreach ($data['rates'] as $rate) {
    // Prices are decimal strings or null (= not configured). Keep them as strings
    // (e.g. bcmath) rather than float for money.
    $sellToCustomer = $rate['customerPrice']['retail']['buy'];
    echo $rate['code'], ': ', $sellToCustomer ?? 'not configured', PHP_EOL;
}

import os
from decimal import Decimal

import requests

API_KEY = os.environ["HAMTA_API_KEY"]  # hamta_live_...

resp = requests.get(
    "https://hamtagift.com/api/partner/v1/rates",
    headers={"Authorization": f"Bearer {API_KEY}", "Accept": "application/json"},
    timeout=10,
)
try:
    data = resp.json()
except ValueError:  # plain-text 403/429 from the security layer
    data = None
if resp.status_code != 200 or not data or not data.get("ok"):
    # 401: check the key. 429: wait for Retry-After. 503: keep your last good prices.
    raise RuntimeError(f"Hamta API error: {(data or {}).get('error', resp.status_code)}")

for rate in data["rates"]:
    price = rate["customerPrice"]["retail"]["buy"]  # decimal string or None
    print(rate["code"], Decimal(price) if price is not None else "not configured")

// Node.js 18+, ES module (.mjs). Server side only.
const API_KEY = process.env.HAMTA_API_KEY; // hamta_live_...

const res = await fetch("https://hamtagift.com/api/partner/v1/rates", {
  headers: { Authorization: `Bearer ${API_KEY}`, Accept: "application/json" },
  signal: AbortSignal.timeout(10_000),
});
const data = await res.json().catch(() => null); // null for the plain-text 403/429
if (!res.ok || !data?.ok) {
  // 401: check the key. 429: wait for Retry-After. 503: keep your last good prices.
  throw new Error(`Hamta API error: ${data?.error ?? `HTTP ${res.status}`}`);
}

for (const rate of data.rates) {
  // Decimal strings or null; parse with a decimal library, not Number, for money.
  console.log(rate.code, rate.customerPrice.retail.buy ?? "not configured");
}

# HAMTA_API_KEY holds your key (hamta_live_...)
curl -sS "https://hamtagift.com/api/partner/v1/rates" \
  -H "Authorization: Bearer $HAMTA_API_KEY" \
  -H "Accept: application/json"

Öneriler

• Her sayfa görüntülemesinde yeni istek göndermek yerine sonucu sunucunuzda en az bir dakika önbelleğe alın.
• Fiyatları kayan noktalı sayı (float) olarak değil, dize veya tam ondalık tip (Decimal, bcmath) olarak işleyin.
• Enstrümanları code alanıyla bulun; label yalnızca görüntüleme içindir.
• null değerini “ayarlanmadı” olarak gösterin ve yerine asla başka bir sayı koymayın.
• Bir istek başarısız olursa son geçerli kurları updatedAt zamanlarıyla birlikte koruyun.
• Her hizmet veya ortam için ayrı bir anahtar oluşturun; gerektiğinde yalnızca onu iptal edebilirsiniz.