Hamta գործընկերների փոխարժեքների API

Ընդհանուր

Hamta API-ն միայն ընթերցման REST ծառայություն է, որը պատասխանը վերադարձնում է JSON ձևաչափով՝ UTF-8 կոդավորմամբ։ Յուրաքանչյուր API բանալի պատկանում է մեկ գործընկերային հաշվի և վերադարձնում է միայն այդ հաշվի փոխարժեքները՝ ձեր ինքնարժեքը Hamta-ից և ձեր հաճախորդի գինը՝ գործընկերների վահանակում ձեր իսկ սահմանած հավելագնով։ Շուկայի հղումային փոխարժեքներ այս API-ն չի տրամադրում։

Նույնականացում

Յուրաքանչյուր հարցում պետք է API բանալին ուղարկի Authorization վերնագրում՝ Bearer ձևով։ Բանալիները սկսվում են hamta_live_ նախածանցով։

1. Մուտք գործեք գործընկերների վահանակ և բացեք «API և Telegram» էջը։
2. Ստեղծեք նոր բանալի (Սեփականատեր, Կառավարիչ և Մշակող դերերը կարող են բանալի ստեղծել)։
3. Բանալին ցուցադրվում է միայն մեկ անգամ․ պահեք այն ձեր սերվերի անվտանգ միջավայրի փոփոխականում։ Hamta-ն պահում է միայն բանալու գաղտնագրված (հեշ) պատճենը․ եթե կորցնեք բանալին, չեղարկեք այն և ստեղծեք նորը։

Authorization: Bearer hamta_live_…

Երբեք մի տեղադրեք API բանալին զննարկչի կողմի կոդում (էջի JavaScript), բջջային հավելվածում կամ հանրային կոդի պահոցում։ Հարցումներն ուղարկեք միայն ձեր սերվերից։

Փոխարժեքների ստացում

Վերադարձնում է ձեր գործընկերային հաշվի բոլոր գործիքների ընթացիկ փոխարժեքները։ Հարցումը պարամետրեր կամ մարմին չունի, և պատասխանը երբեք չի քեշավորվում (Cache-Control: no-store)։

Ժամեր և հասանելիություն

Փոխարժեքների API-ն պատասխանում է շուկայի աշխատանքային օրերին՝ Թեհրանի ժամանակով 11:00-ից 20:00 (վերջին ընդունվող հարցումը՝ 19:59-ին)։ Ուրբաթ օրերին և շուկայի պաշտոնական տոն օրերին այն փակ է։ Այս ժամերից դուրս վերադարձվում է 503՝ OUTSIDE_MARKET_HOURS կոդով․ Retry-After վերնագիրը ցույց է տալիս մինչև հաջորդ բացումը մնացած վայրկյանները, իսկ next_open դաշտը՝ բացման ժամը (ISO 8601, UTC)։

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

Թույլատրված IP-ների ցուցակը կամընտիր է և գրանցվում է Hamta-ի աջակցության կողմից՝ ձեր խնդրանքով։ Քանի դեռ ոչ մի հասցե գրանցված չէ, ձեր բանալիներն ընդունվում են ցանկացած IP-ից։ Եթե գրանցվի մեկ կամ մի քանի հասցե, ցանկացած այլ հասցեից եկող հարցում կմերժվի 403-ով և IP_NOT_ALLOWED կոդով։ Ընդունվում են միայն ճշգրիտ հանրային IPv4 կամ IPv6 հասցեներ (առանց միջակայքերի), առավելագույնը 10․ ցուցակը կիրառվում է ձեր հաշվի բոլոր բանալիների համար և երևում է գործընկերների վահանակում (API և Telegram բաժին)։

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

Պատասխան

Հաջող պատասխանը վերադառնում է 200 կարգավիճակով։ Ստորև բերված կառուցվածքը ճշգրտորեն այն բանալիներն են, որոնք վերադարձնում է API-ն․ թվային արժեքների փոխարեն գրված է տվյալի տեսակը։ Ձեր հաշվի իրական պատասխանը տեսնելու համար բացեք գործընկերների վահանակի «API և Telegram» էջը։

{
  "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>"
        }
      }
    },
    …
  ]
}

Դաշտեր

Բոլոր գները տասնորդական թվի տող են (մինչև 6 տասնորդական նիշ) կամ null։ null նշանակում է «կարգավորված չէ»․ երբեք այն զրո մի համարեք։

Գործիքներ

rates ցանկը միշտ պարունակում է այս գործիքները՝ այս հերթականությամբ․

Սխալներ

API-ի սխալները վերադառնում են JSON ձևաչափով՝ "ok": false և "error" դաշտում կոդով։ IP_NOT_ALLOWED և OUTSIDE_MARKET_HOURS սխալները լրացուցիչ պարունակում են "success": false և "message"՝ ձեր Accept-Language վերնագրի լեզվով (fa, en, tr, hy, հակառակ դեպքում՝ անգլերեն)։ Աղյուսակի վերջին երկու տողերը գալիս են կայքի անվտանգության շերտից և պարզ տեքստ են, ոչ թե JSON։

Սահմանաչափեր

• Առավելագույնը 60 հարցում րոպեում՝ յուրաքանչյուր API բանալու համար։
• Հարցումներին պատասխանվում է միայն շուկայի աշխատանքային օրերին՝ Թեհրանի ժամանակով 11:00–20:00 (տե՛ս «Ժամեր և հասանելիություն»)։
• Թույլատրված IP ցուցակի պատճառով մերժված հարցումները չեն հաշվվում ձեր բանալու րոպեական սահմանաչափի մեջ։
• Բացի այդ, յուրաքանչյուր IP հասցե ունի կայքի ընդհանուր առանձին սահմանաչափ (անընդհատ՝ վայրկյանում մոտ 2 հարցումից ոչ ավելի)։
• Աջակցվում է միայն GET մեթոդը։

Պատրաստի կոդի օրինակներ

Ստորև բերված օրինակները բանալին կարդում են HAMTA_API_KEY միջավայրի փոփոխականից, ստուգում են սխալները և տպում յուրաքանչյուր գործիքի մանրածախ հաճախորդային գինը։ PHP օրինակը հարմար է WooCommerce-ի կամ Laravel-ի նման առցանց խանութների համար։

<?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"

Խորհուրդներ

• Քեշավորեք արդյունքը ձեր սերվերում առնվազն մեկ րոպե՝ յուրաքանչյուր էջի դիտման համար նոր հարցում ուղարկելու փոխարեն։
• Մշակեք գները որպես տող կամ ճշգրիտ տասնորդական տեսակ (Decimal, bcmath), ոչ թե լողացող կետով թիվ (float)։
• Գործիքները փնտրեք code դաշտով․ label-ը միայն ցուցադրման համար է։
• null արժեքը ցուցադրեք որպես «կարգավորված չէ» և երբեք դրա փոխարեն այլ թիվ մի դրեք։
• Եթե հարցումը ձախողվի, պահեք վերջին վավեր փոխարժեքները՝ դրանց updatedAt ժամանակի հետ միասին։
• Յուրաքանչյուր ծառայության կամ միջավայրի համար ստեղծեք առանձին բանալի, որպեսզի անհրաժեշտության դեպքում չեղարկեք միայն այն։