Kimlik doğrulama

Her isteğin gövdesinde bir auth nesnesi bulunur. İki yöntemden birini seçebilirsiniz; ikisi aynı isteği karşılar.

Yöntem	auth içeriği	Ne zaman
Anahtar	{ "apiKey": "…", "secKey": "…" }	En basit yol. İstek TLS ile şifrelendiği için güvenlidir.
İmza	{ "site": "…", "hash": "…" }	secKey'in ağ üzerinden hiç gitmemesini istiyorsanız.

Anahtarlarınız:

• apiKey tlh_pk_ ile başlar.
• secKey tlh_sk_ ile başlar. Gizlidir; hem anahtar yönteminde hem de bildirim imzalarında kullanılır.

secKey yalnızca sunucuda durur

secKey'i istemci koduna, mobil uygulamaya, URL'ye veya log'a koymayın. Sızdığını düşünüyorsanız hesap yöneticinizden anahtarları yenilemesini isteyin; yenileme anında eski anahtarlar geçersiz olur.

Anahtar yöntemi

{
  "auth": { "apiKey": "tlh_pk_…", "secKey": "tlh_sk_…" },
  "customer": { "fullName": "Ayşe Demir", "username": "aysed", "id": "48213" },
  "amount": 1500,
  "transactionId": "dep-2026-000184"
}

İki anahtar birlikte eşleşmelidir.

İmza yöntemi

site alanına hesap yöneticinizin size bildirdiği site adını yazarsınız. hash şöyle hesaplanır:

hash = sha1( secKey + JSON(auth hariç gövde) )

Sonuç küçük harfli onaltılık (hex) metindir. Sunucu gövdeden auth'u çıkarır, kalanı JSON'a çevirip aynı hesabı yapar.

JSON birebir aynı olmalı

İmza, gönderdiğiniz JSON'un sunucuda yeniden üretilmiş hâli üzerinden doğrulanır. Bu yüzden:

• Boşluksuz (kompakt) JSON kullanın.
• Alanları imzaladığınız sırayla gönderin; auth'u en sona ekleyin.
• Türkçe karakterleri ve / işaretini kaçış dizisine çevirmeyin (ç, \/ olmasın).
• Sayıları sayı olarak gönderin (1500, "1500" değil).

Node.js

const crypto = require("crypto");

function signedBody(site, secKey, payload) {
  const json = JSON.stringify(payload);
  const hash = crypto.createHash("sha1").update(secKey + json).digest("hex");
  // auth en sonda: sunucu onu çıkardığında kalan JSON imzalananla aynı olur
  return { ...payload, auth: { site, hash } };
}

PHP

function signedBody(string $site, string $secKey, array $payload): string {
    $flags = JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES;
    $hash = sha1($secKey . json_encode($payload, $flags));
    $payload['auth'] = ['site' => $site, 'hash' => $hash];
    return json_encode($payload, $flags);
}

Python

import hashlib, json

def signed_body(site: str, sec_key: str, payload: dict) -> str:
    raw = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
    digest = hashlib.sha1((sec_key + raw).encode("utf-8")).hexdigest()
    return json.dumps({**payload, "auth": {"site": site, "hash": digest}},
                      ensure_ascii=False, separators=(",", ":"))

IP izin listesi

Sunucu IP adreslerinizi hesap yöneticinize bildirirseniz API yalnızca bu adreslerden gelen istekleri kabul eder. Listede olmayan bir adresten gelen istek 403 ve [022] ekiyle reddedilir. Sunucu IP'niz değişecekse önceden haber verin.

İstek sınırı

Partner uç noktaları için IP başına dakikada 60 istek sınırı vardır. Sınır aşılırsa istek kısa bir süre reddedilir; yeniden denemeden önce birkaç saniye bekleyin.