Kimlik Doğrulama

Korumalı tüm endpoint'ler için iki request header gereklidir:

Header	Açıklama
`X-API-KEY`	Hesabınıza ait kalıcı API anahtarı
`X-SIGNATURE`	Her istek için ayrı hesaplanan, request body'sine dayalı imza

API key ve API secret, TradeAtlas portalındaki Profil sekmesinden alınır. Secret hiçbir zaman header olarak gönderilmez — yalnızca X-SIGNATURE üretmek için kullanılır.

1. API Key ve Secret Edinme

API key ve secret'ınızı TradeAtlas portalında Profil sekmesinden alabilirsiniz. Her ikisi de kalıcı değerlerdir; secret'ı güvenli şekilde saklayın ve asla istemci tarafında (tarayıcı, mobil uygulama) ifşa etmeyin.

TradeAtlas portalında üst menüden API sekmesine geçin. API Anahtarı (API Key) ve API Parolası (API Secret) alanlarını buradan Oluştur butonuyla üretebilirsiniz. Parola yalnızca bir kez gösterilir — güvenli bir yerde saklayın.

2. X-API-KEY

API key, TradeAtlas portalındaki Profil sekmesinden bir kez oluşturulur. Kalıcı bir değerdir — her istekte aynı key kullanılır.

X-API-KEY: api-keyiniz

3. X-SIGNATURE

Signature isteğe özgüdür ve her request için yeniden hesaplanmalıdır. Request payload'ının, API secret ile HMAC-SHA256 imzalanıp Base64 encode edilmesiyle elde edilir.

signature = Base64( HMACSHA256( requestPayload, apiSecret ) )

requestPayload — request body olarak gönderilen ham JSON string. Body'siz isteklerde (örn. GET) boş string "" kullanılır.
apiSecret — TradeAtlas portalındaki Profil sekmesinden alınan değer.

ÖNEMLİ

İmza, gönderdiğiniz body'nin birebir aynısı üzerinden hesaplanmalıdır. JSON'ı imzaladıktan sonra yeniden serialize eder (boşluk, alan sırası değişir) veya farklı bir gövde gönderirseniz imza geçersiz olur ve 401 alırsınız.

İmza Hesaplama

JavaScriptcURLJavaPython

import crypto from 'crypto'

const payload = '{"page":1,"search_type":"importer"}'
const apiSecret = 'api-secretiniz'

const signature = crypto
  .createHmac('sha256', apiSecret)
  .update(payload)
  .digest('base64')

bash

PAYLOAD='{"page":1,"search_type":"importer"}'

SIGNATURE=$(echo -n "$PAYLOAD" \
  | openssl dgst -sha256 -hmac "api-secretiniz" -binary \
  | base64)

java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;
import java.nio.charset.StandardCharsets;

String payload   = "{\"page\":1,\"search_type\":\"importer\"}";
String apiSecret = "api-secretiniz";

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(apiSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] hash = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
String signature = Base64.getEncoder().encodeToString(hash);

python

import hmac, hashlib, base64

payload    = '{"page":1,"search_type":"importer"}'
api_secret = "api-secretiniz"

signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

4. Tam İstek Örneği

Aşağıdaki örnekler payload'ı imzalayıp X-API-KEY ve X-SIGNATURE header'larıyla birlikte gönderir.

JavaScriptcURLJavaPython

import crypto from 'crypto'

const payload = JSON.stringify({
  page: 1,
  search_type: 'importer',
  importer_countries: ['US'],
  hs_codes: ['847130']
})

const signature = crypto
  .createHmac('sha256', 'api-secretiniz')
  .update(payload)
  .digest('base64')

const res = await fetch('https://apiv2.tradeatlas.com/api/v1/firms/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'api-keyiniz',
    'X-SIGNATURE': signature
  },
  body: payload
})

const data = await res.json()

bash

PAYLOAD='{"page":1,"search_type":"importer","importer_countries":["US"],"hs_codes":["847130"]}'

SIGNATURE=$(echo -n "$PAYLOAD" \
  | openssl dgst -sha256 -hmac "api-secretiniz" -binary \
  | base64)

curl -X POST https://apiv2.tradeatlas.com/api/v1/firms/search \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: api-keyiniz" \
  -H "X-SIGNATURE: $SIGNATURE" \
  -d "$PAYLOAD"

java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

String payload = "{\"page\":1,\"search_type\":\"importer\",\"importer_countries\":[\"US\"],\"hs_codes\":[\"847130\"]}";

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec("api-secretiniz".getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String signature = Base64.getEncoder()
    .encodeToString(mac.doFinal(payload.getBytes(StandardCharsets.UTF_8)));

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://apiv2.tradeatlas.com/api/v1/firms/search"))
    .header("Content-Type", "application/json")
    .header("X-API-KEY", "api-keyiniz")
    .header("X-SIGNATURE", signature)
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

python

import hmac, hashlib, base64, requests

payload = '{"page":1,"search_type":"importer","importer_countries":["US"],"hs_codes":["847130"]}'

signature = base64.b64encode(
    hmac.new("api-secretiniz".encode(), payload.encode(), hashlib.sha256).digest()
).decode()

response = requests.post(
    "https://apiv2.tradeatlas.com/api/v1/firms/search",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "api-keyiniz",
        "X-SIGNATURE": signature,
    },
    data=payload,
)
data = response.json()

Sık Karşılaşılan Hatalar

Durum	Olası Neden	Çözüm
`401 Unauthorized`	`X-API-KEY` veya `X-SIGNATURE` eksik/hatalı	Header'ların gönderildiğini ve key'in doğru olduğunu kontrol edin
`401` (imza uyuşmuyor)	İmza, gönderilen body'den farklı bir string üzerinden hesaplanmış	İmzayı birebir gönderdiğiniz body üzerinden hesaplayın; JSON'ı tekrar serialize etmeyin
`401` (secret yanlış)	Yanlış veya süresi dolmuş API secret	Profil sekmesindeki güncel secret'ı kullanın

Detaylı hata kodları için Hatalar sayfasına bakın.

Kimlik Doğrulama ​

1. API Key ve Secret Edinme ​

2. X-API-KEY ​

3. X-SIGNATURE ​

İmza Hesaplama ​

4. Tam İstek Örneği ​