Այս էջը ներկայումս հասանելի է միայն պարսկերենով։
HamtaGift գործընկերների փոխարժեքների API
Այս API-ի միջոցով ձեր կայքը, առցանց խանութը կամ բոտը ստանում է ձեր գործընկերային հաշվի փոխարժեքները անմիջապես HamtaGift-ից՝ առանց գների ձեռքով մուտքագրման և միշտ համաժամեցված գործընկերների վահանակի հետ։
Ընդհանուր
HamtaGift API-ն միայն ընթերցման REST ծառայություն է, որը պատասխանը վերադարձնում է JSON ձևաչափով՝ UTF-8 կոդավորմամբ։ Յուրաքանչյուր API բանալի պատկանում է մեկ գործընկերային հաշվի և վերադարձնում է միայն այդ հաշվի փոխարժեքները՝ ձեր ինքնարժեքը HamtaGift-ից և ձեր հաճախորդի գինը՝ գործընկերների վահանակում ձեր իսկ սահմանած հավելագնով։ Շուկայի հղումային փոխարժեքներ այս API-ն չի տրամադրում։
https://hamtagift.com
Բոլոր հարցումները պետք է ուղարկվեն HTTPS-ով։
Նույնականացում
Յուրաքանչյուր հարցում պետք է API բանալին ուղարկի Authorization վերնագրում՝ Bearer ձևով։ Բանալիները սկսվում են hamta_live_ նախածանցով։
- Մուտք գործեք գործընկերների վահանակ և բացեք «API և Telegram» էջը։
- Ստեղծեք նոր բանալի (Սեփականատեր, Կառավարիչ և Մշակող դերերը կարող են բանալի ստեղծել)։
- Բանալին ցուցադրվում է միայն մեկ անգամ․ պահեք այն ձեր սերվերի անվտանգ միջավայրի փոփոխականում։ HamtaGift-ը պահում է միայն բանալու գաղտնագրված (հեշ) պատճենը․ եթե կորցնեք բանալին, չեղարկեք այն և ստեղծեք նորը։
Authorization: Bearer hamta_live_…Երբեք մի տեղադրեք API բանալին զննարկչի կողմի կոդում (էջի JavaScript), բջջային հավելվածում կամ հանրային կոդի պահոցում։ Հարցումներն ուղարկեք միայն ձեր սերվերից։
Փոխարժեքների ստացում
Վերադարձնում է ձեր գործընկերային հաշվի գործիքների ընթացիկ փոխարժեքները՝ բոլորը կամ միայն նրանք, որոնք նշում եք ոչ պարտադիր instruments պարամետրով։ Հարցումը մարմին չունի, և պատասխանը երբեք չի քեշավորվում (Cache-Control: no-store)։
Ոչ պարտադիր պարամետր՝ instruments
Միայն որոշ գործիքներ ստանալու համար ավելացրեք instruments=՝ «Գործիքներ» աղյուսակի կոդերով, ստորակետով բաժանված։ Կոդերը զգայուն չեն մեծատառերի և փոքրատառերի նկատմամբ (rub-ը նույնն է, ինչ RUB-ը), բացատներն ու կրկնվող կոդերն անտեսվում են, և rates ցանկը պահպանում է «Գործիքներ» աղյուսակի հերթականությունը՝ անկախ այն բանից, թե ինչ հերթականությամբ եք ուղարկում կոդերը։ Առանց պարամետրի կամ դատարկ արժեքով վերադարձվում են բոլոր գործիքները։ Եթե թեկուզ մեկ կոդ անհայտ է, ոչ մի փոխարժեք չի վերադարձվում․ API-ն պատասխանում է 400՝ unknown_instruments կոդով, անհայտ կոդերը invalid դաշտում են, իսկ բոլոր վավեր կոդերը՝ allowed դաշտում։ Պարամետրը ստուգվում է բանալու, IP-ի, րոպեական սահմանաչափի և շուկայի ժամերի ստուգումներից հետո, ուստի մերժված հարցումը նույնպես հաշվվում է րոպեական սահմանաչափում։
GET /api/partner/v1/rates?instruments=dollar,euro{
"ok": false,
"error": "unknown_instruments",
"invalid": [
"<string>"
],
"allowed": [
"havaleLir",
"dollar",
"euro",
"usdtToLir",
"AMD_1000",
"usdtPrice",
"AFN",
"onlineShop",
"sipay",
"RUB"
]
}Ժամեր և հասանելիություն
Փոխարժեքների 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-ների ցուցակը կամընտիր է և գրանցվում է HamtaGift-ի աջակցության կողմից՝ ձեր խնդրանքով։ Քանի դեռ ոչ մի հասցե գրանցված չէ, ձեր բանալիներն ընդունվում են ցանկացած 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>"
}
}
},
…
]
}Դաշտեր
| Դաշտ | Տեսակ | Նկարագրություն |
|---|---|---|
ok | boolean | Հաջող պատասխանում միշտ true է, սխալի պատասխանում՝ false։ |
partner | string | Ձեր ընկերության անվանումը՝ ինչպես գրանցված է գործընկերային հաշվում։ |
updatedAt | string | null | HamtaGift-ի հղումային փոխարժեքների վերջին թարմացման ժամանակը ISO 8601 (UTC) ձևաչափով․ null, եթե հայտնի չէ։ |
note | string | Ֆիքսված նշում buy, sell և null արժեքների իմաստի մասին։ |
rates | array | Գործիքների ցանկը (բոլորը կամ instruments-ով նշվածները)՝ միշտ «Գործիքներ» աղյուսակի հերթականությամբ։ |
rates[].code | string | Գործիքի կայուն նույնացուցիչ․ ձեր կոդում հենվեք այս դաշտի, ոչ թե label-ի վրա։ |
rates[].label | string | Գործիքի պարսկերեն ցուցադրվող անվանումը․ կարող է փոխվել։ |
rates[].unit | "TOMAN" | "TRY" | Գնի միավորը․ TOMAN՝ իրանական թուման, TRY՝ թուրքական լիրա։ |
rates[].unitBasis | integer | Գինը նշված է այսքան միավորի համար․ օրինակ՝ 1000 նշանակում է 1000 միավորի գին։ |
rates[].partnerCost | { retail, wholesale } | Ձեր ինքնարժեքը HamtaGift-ից՝ բաժանված մանրածախ (retail) և մեծածախ (wholesale) մակարդակների։ |
rates[].customerPrice | { retail, wholesale } | Ձեր հաճախորդի գինը՝ ձեր ինքնարժեքը գումարած գործընկերների վահանակում ձեր սահմանած հավելագինը (լռելյայն՝ 1%)։ Զեղչային արշավի ժամանակ այդ հավելագինը կարող է իջնել մինչև -2%, և հաճախորդի գինը կարող է ավելի շահավետ լինել, քան ձեր ինքնարժեքը։ null է, եթե այդ ուղղության համար հավելագին սահմանված չէ։ |
….buy | string | null | Գինը, որով ձեր հաճախորդը գնում է ձեզանից։ |
….sell | string | null | Գինը, որով ձեր հաճախորդը վաճառում է ձեզ։ |
Բոլոր գները տասնորդական թվի տող են (մինչև 6 տասնորդական նիշ) կամ null։ null նշանակում է «կարգավորված չէ»․ երբեք այն զրո մի համարեք։
Գործիքներ
Առանց instruments պարամետրի rates ցանկը պարունակում է այս բոլոր գործիքները՝ այս հերթականությամբ․
| code | Գործիք | unit | unitBasis |
|---|---|---|---|
havaleLir | Թուրքական լիրայի փոխանցում (թուման՝ մեկ լիրայի դիմաց) | TOMAN | 1 |
dollar | ԱՄՆ դոլար (թուման՝ մեկ դոլարի դիմաց) | TOMAN | 1 |
euro | Եվրո (թուման՝ մեկ եվրոյի դիմաց) | TOMAN | 1 |
usdtToLir | Թուրքական լիրա՝ մեկ USDT-ի դիմաց | TRY | 1 |
AMD_1000 | Հայկական դրամ (թուման՝ 1000 դրամի դիմաց) | TOMAN | 1000 |
usdtPrice | Թուման՝ մեկ USDT-ի դիմաց | TOMAN | 1 |
AFN | Աֆղանական աֆղանի (թուման՝ մեկ աֆղանիի դիմաց) | TOMAN | 1 |
onlineShop | Առցանց գնումների լիրա (թուման՝ մեկ լիրայի դիմաց) | TOMAN | 1 |
sipay | HamtaCard լիրա (թուման՝ մեկ լիրայի դիմաց) | TOMAN | 1 |
RUB | Ռուսական ռուբլի (թուման՝ մեկ ռուբլու դիմաց) | TOMAN | 1 |
Սխալներ
API-ի սխալները վերադառնում են JSON ձևաչափով՝ "ok": false և "error" դաշտում կոդով։ IP_NOT_ALLOWED և OUTSIDE_MARKET_HOURS սխալները լրացուցիչ պարունակում են "success": false և "message"՝ ձեր Accept-Language վերնագրի լեզվով (fa, en, tr, hy, հակառակ դեպքում՝ անգլերեն)։ Աղյուսակի վերջին երկու տողերը գալիս են կայքի անվտանգության շերտից և պարզ տեքստ են, ոչ թե JSON։
| Կարգավիճակ | error | Իմաստը | Ինչ անել |
|---|---|---|---|
401 | missing_or_malformed_token | Authorization վերնագիրը բացակայում է, կամ բանալին hamta_live_ ձևաչափով չէ։ | Ուղարկեք վերնագիրը Bearer ձևով՝ ամբողջական բանալիով։ |
401 | invalid_token | Բանալին անհայտ է կամ չեղարկված, կամ գործընկերային հաշիվը ակտիվ չէ։ | Ստեղծեք նոր բանալի գործընկերների վահանակում կամ կապվեք HamtaGift-ի հետ։ |
403 | IP_NOT_ALLOWED | Բանալին վավեր է, սակայն հարցումը չի եկել ձեր հաշվի թույլատրված IP ցուցակի հասցեից։ | Ուղարկեք գրանցված հասցեից կամ ցուցակը փոխելու համար կապվեք HamtaGift-ի աջակցության հետ։ |
429 | rate_limited | Այս բանալիով մեկ րոպեում 60-ից ավելի հարցում։ | Սպասեք Retry-After վերնագրում նշված ժամանակը (վայրկյան) և քեշավորեք արդյունքը։ |
503 | OUTSIDE_MARKET_HOURS | Շուկայի ժամերից դուրս (Թեհրանի ժամանակով 11:00–20:00) կամ շուկայի տոն օր։ | Սպասեք Retry-After-ին կամ next_open-ին և շարունակեք ցույց տալ ձեր վերջին վավեր փոխարժեքները։ |
400 | unknown_instruments | instruments պարամետրը պարունակում է գոյություն չունեցող կոդ։ | Ուղարկեք միայն allowed դաշտում կամ «Գործիքներ» աղյուսակում նշված կոդերը։ |
503 | rates_unavailable | Փոխարժեքները ժամանակավորապես հասանելի չեն։ | Պահեք ձեր վերջին վավեր փոխարժեքները և փորձեք ավելի ուշ։ |
403 | — | Հարցումը մերժվել է կայքի անվտանգության կանոններով (պարզ տեքստ՝ Forbidden)։ | Եթե ձեր հարցումը սովորական է, կապվեք HamtaGift-ի աջակցության հետ։ |
429 | — | Չափազանց շատ հարցումներ մեկ IP հասցեից (պարզ տեքստ)։ | Սպասեք Retry-After ժամանակը և մեծացրեք հարցումների միջև ընդմիջումը։ |
Սահմանաչափեր
- Առավելագույնը 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 ժամանակի հետ միասին։
- Յուրաքանչյուր ծառայության կամ միջավայրի համար ստեղծեք առանձին բանալի, որպեսզի անհրաժեշտության դեպքում չեղարկեք միայն այն։
Պատրա՞ստ եք միանալու
API բանալիները ստեղծվում են գործընկերների վահանակում։ Եթե դեռ HamtaGift-ի գործընկեր չեք, կապվեք մեզ հետ՝ գործընկերային հաշիվ բացելու համար։