Türk lirası (havale)Perakende5,680 Tomen• 0.00%ABD dolarıPerakende280,770 Tomen• 0.00%EuroPerakende309,220 Tomen• 0.00%USDT → TLPerakende54.92 TL• 0.00%Türk lirası (havale)Toptan5,570 Tomen• —ABD dolarıToptan276,720 Tomen• —EuroToptan304,760 Tomen• —USDT → TLToptan53.90 TL• —
Son güncelleme: 21 Kas 2026 00:40 (Tahran saati)

Bu sayfa şu anda yalnızca Farsça olarak mevcuttur.

Geliştirici dokümantasyonu

HamtaGift İş Ortağı Kur API'si

Bu API ile web siteniz, e-ticaret mağazanız veya botunuz, iş ortağı hesabınızın kurlarını doğrudan HamtaGift'ten alır: elle fiyat girişi olmadan, her zaman iş ortağı paneliyle eş zamanlı.

Genel bakış

HamtaGift 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: HamtaGift'ten maliyetiniz ve iş ortağı panelinde kendi belirlediğiniz marjla müşteri fiyatınız. Piyasa referans kurları bu API'de sunulmaz.

Temel adres

https://hamtagift.com

Tüm istekler HTTPS üzerinden gönderilmelidir.

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. HamtaGift yalnızca anahtarın şifrelenmiş (hash) kopyasını tutar; anahtarı kaybederseniz iptal edip yenisini oluşturun.
İstek başlığı
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

GET/api/partner/v1/rates

İş ortağı hesabınızdaki enstrümanların güncel kurlarını döndürür: tümünü ya da yalnızca isteğe bağlı instruments parametresiyle belirttiklerinizi. İstek gövde almaz ve yanıt hiçbir zaman önbelleğe alınmaz (Cache-Control: no-store).

İsteğe bağlı parametre: instruments

Yalnızca bazı enstrümanları almak için Enstrümanlar tablosundaki kodlarını virgülle ayırarak instruments= ile ekleyin. Kodlar büyük/küçük harfe duyarlı değildir (rub ile RUB aynıdır); boşluklar ve tekrarlanan kodlar yok sayılır ve rates listesi, kodları hangi sırayla gönderirseniz gönderin, Enstrümanlar tablosundaki sırayı korur. Parametre yoksa veya boşsa tüm enstrümanlar döner. Kodlardan biri bile bilinmiyorsa hiçbir kur dönmez: API unknown_instruments koduyla 400 yanıtı verir; bilinmeyen kodlar invalid, tüm geçerli kodlar allowed alanındadır. Parametre anahtar, IP, dakikalık sınır ve piyasa saatleri kontrollerinden sonra denetlenir; bu nedenle reddedilen istek de dakikalık sınıra sayılır.

Örnek istek
GET /api/partner/v1/rates?instruments=dollar,euro
400
{
  "ok": false,
  "error": "unknown_instruments",
  "invalid": [
    "<string>"
  ],
  "allowed": [
    "havaleLir",
    "dollar",
    "euro",
    "usdtToLir",
    "AMD_1000",
    "usdtPrice",
    "AFN",
    "onlineShop",
    "sipay",
    "RUB"
  ]
}

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.

503
{
  "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 HamtaGift 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.

403
{
  "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.

Başarılı yanıtın yapısı
{
  "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

AlanTipAçıklama
okbooleanBaşarılı yanıtta her zaman true, hata yanıtında false'tur.
partnerstringİş ortağı hesabında kayıtlı şirket adınız.
updatedAtstring | nullHamtaGift referans kurlarının son güncellenme zamanı, ISO 8601 (UTC); bilinmiyorsa null.
notestringbuy, sell ve null anlamlarına dair sabit bir not.
ratesarrayEnstrüman listesi (tümü veya instruments ile belirttikleriniz), her zaman Enstrümanlar tablosundaki sırayla.
rates[].codestringEnstrümanın sabit kimliği; kodunuzda label'a değil bu alana güvenin.
rates[].labelstringEnstrümanın Farsça görünen adı; değişebilir.
rates[].unit"TOMAN" | "TRY"Fiyat birimi: TOMAN İran tümeni, TRY Türk lirasıdır.
rates[].unitBasisintegerFiyat bu kadar birim içindir; örneğin 1000, 1.000 birimin fiyatı demektir.
rates[].partnerCost{ retail, wholesale }HamtaGift'ten maliyetiniz; perakende (retail) ve toptan (wholesale) kademelerine ayrılmış.
rates[].customerPrice{ retail, wholesale }Müşteri fiyatınız: maliyetiniz artı iş ortağı panelinde belirlediğiniz marj (varsayılan %1). İndirim kampanyasında bu marj -%2'ye kadar inebilir; bu durumda müşteri fiyatı maliyetinizden daha avantajlı olur. O yön için marj belirlenmemişse null.
….buystring | nullMüşterinizin sizden satın aldığı fiyat.
….sellstring | nullMüşterinizin size sattığı fiyat.

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

instruments parametresi olmadan rates listesi bu enstrümanların tümünü bu sırayla içerir:

codeEnstrümanunitunitBasis
havaleLirTürk lirası havale (lira başına tümen)TOMAN1
dollarABD doları (dolar başına tümen)TOMAN1
euroEuro (euro başına tümen)TOMAN1
usdtToLirUSDT başına Türk lirasıTRY1
AMD_1000Ermeni dramı (1.000 dram başına tümen)TOMAN1000
usdtPriceUSDT başına tümenTOMAN1
AFNAfgan afganisi (afgani başına tümen)TOMAN1
onlineShopOnline alışveriş lirası (lira başına tümen)TOMAN1
sipayHamtaCard lirası (lira başına tümen)TOMAN1
RUBRus rublesi (ruble başına tümen)TOMAN1

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.

DurumerrorAnlamıYapılacak
401missing_or_malformed_tokenAuthorization başlığı yok veya anahtar hamta_live_ biçiminde değil.Başlığı Bearer olarak ve anahtarın tamamıyla gönderin.
401invalid_tokenAnahtar tanınmıyor veya iptal edilmiş ya da iş ortağı hesabı aktif değil.İş ortağı panelinde yeni anahtar oluşturun veya HamtaGift ile iletişime geçin.
403IP_NOT_ALLOWEDAnahtar geçerli, ancak istek hesabınızın izinli IP listesindeki bir adresten gelmedi.Kayıtlı bir adresten gönderin veya listeyi değiştirmek için HamtaGift desteğiyle iletişime geçin.
429rate_limitedBu anahtarla bir dakikada 60'tan fazla istek.Retry-After başlığındaki süre (saniye) kadar bekleyin ve sonucu önbelleğe alın.
503OUTSIDE_MARKET_HOURSPiyasa saatleri dışında (Tahran saatiyle 11:00–20:00) veya piyasa tatilinde.Retry-After ya da next_open zamanını bekleyin ve son geçerli kurlarınızı göstermeye devam edin.
400unknown_instrumentsinstruments parametresinde var olmayan bir kod var.Yalnızca allowed alanındaki veya Enstrümanlar tablosundaki kodları gönderin.
503rates_unavailableKurlar geçici olarak kullanılamıyor.Son geçerli kurlarınızı koruyun ve daha sonra tekrar deneyin.
403—İstek, sitenin güvenlik kuralları tarafından reddedildi (düz metin Forbidden).İsteğiniz olağansa HamtaGift desteğiyle iletişime geçin.
429—Tek bir IP adresinden çok fazla istek (düz metin).Retry-After kadar bekleyin ve istekler arasındaki süreyi artırın.

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;
}

Ö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.

Bağlanmaya hazır mısınız?

API anahtarlarını iş ortağı panelinde oluşturursunuz. Henüz HamtaGift iş ortağı değilseniz, iş ortağı hesabı açmak için bizimle iletişime geçin.