Kimlik Doğrulama ve Token Alma

Kullanıcı Girişi #

Pazaryeri servislerine istek atabilmek için öncelikle authentication (kimlik doğrulama) servisi ile token almanız gerekmektedir.

Bu token, diğer tüm API isteklerinde Authorization header'ında kullanılacaktır.

Authenticate Servisi #

Endpoint Bilgileri #

TEST Ortamı:

POST https://apitest.paynkolay.com.tr/marketplace/v1/authenticate

PROD Ortamı:

POST https://api.paynkolay.com.tr/marketplace/v1/authenticate

İstek Parametreleri #

{
  "username": "nkolay_marketplace",
  "password": "nkolaypassword",
  "merchantNo": "400000904"
}

Parametre Açıklamaları #

Parametre	Tip	Zorunlu	Açıklama
username	String	✅	Sizin için oluşturulmuş kullanıcı adı bilgisi
password	String	✅	Sizin için oluşturulmuş şifre bilgisi
merchantNo	String	✅	Sizin için oluşturulmuş üye işyeri numarası

Güvenlik Uyarısı
Yukarıdaki değerler örnek değerlerdir. Gerçek username, password ve merchantNo değerleriniz Paynkolay tarafından size özel olarak verilecektir.

Bu bilgileri asla kodunuza hardcode etmeyin, güvenli bir şekilde environment variables veya secure vault'larda saklayın.

Yanıt Formatı #

Başarılı bir kimlik doğrulama işlemi sonrasında aşağıdaki gibi bir yanıt alırsınız:

{
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS",
  "data": {
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJua29sYXlfbWFya2V0cGxhY2UiLCJleHAiOjE3NjI5NDY0NTYsImlhdCI6MTc2Mjk0NDY1Nn0.KzUrZmGymeI0Tzqss8XNJzWrCrVmPEtcbep1hXDpqxZ4ALHNk3DQoepdVWWsXs6gnhj3njWgk2klHcrBfn2OLw"
  }
}

Yanıt Parametreleri #

Parametre	Tip	Açıklama
success	Boolean	İşlemin başarılı olup olmadığını gösterir
responseCode	String	İşlem sonucu kodu (200 = Başarılı)
responseMessage	String	İşlem sonucu mesajı
data.token	String	JWT formatında access token (Bearer token olarak kullanılacak)

Token Kullanımı #

Aldığınız token'ı diğer API isteklerinde Authorization header'ında Bearer Token olarak kullanmalısınız.

Örnek Kullanım #

curl -X POST https://apitest.paynkolay.com.tr/marketplace/v1/seller/get \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "sellerExternalId": "SELLER123"
  }'

JavaScript/TypeScript Örneği #

// Token alma
const getToken = async () => {
  const response = await fetch(
    'https://apitest.paynkolay.com.tr/marketplace/v1/authenticate',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        username: process.env.MARKETPLACE_USERNAME,
        password: process.env.MARKETPLACE_PASSWORD,
        merchantNo: process.env.MARKETPLACE_MERCHANT_NO,
      }),
    }
  );

  const data = await response.json();
  return data.data.token;
};

// Token ile API çağrısı
const callAPI = async (token) => {
  const response = await fetch(
    'https://apitest.paynkolay.com.tr/marketplace/v1/seller/get',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        sellerExternalId: 'SELLER123',
      }),
    }
  );

  return await response.json();
};

PHP Örneği #

<?php
// Token alma
function getToken($username, $password, $merchantNo) {
    $url = 'https://apitest.paynkolay.com.tr/marketplace/v1/authenticate';

    $data = [
        'username' => $username,
        'password' => $password,
        'merchantNo' => $merchantNo
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json'
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    $result = json_decode($response, true);
    return $result['data']['token'];
}

// Token ile API çağrısı
function callAPI($token, $sellerExternalId) {
    $url = 'https://apitest.paynkolay.com.tr/marketplace/v1/seller/get';

    $data = [
        'sellerExternalId' => $sellerExternalId
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// Kullanım
$token = getToken(
    getenv('MARKETPLACE_USERNAME'),
    getenv('MARKETPLACE_PASSWORD'),
    getenv('MARKETPLACE_MERCHANT_NO')
);

$result = callAPI($token, 'SELLER123');
?>

Token Yönetimi #

Token Süresi #

JWT token'lar belirli bir süre sonra expire olur (geçersiz hale gelir)
Token'ın exp (expiration) claim'i içinde geçerlilik süresi bulunur
Token geçersiz olduğunda yeni bir token almanız gerekir

Best Practices #

Token'ı Cache'leyin: Her API isteğinde yeni token almak yerine, mevcut token'ı kullanın
Token Yenileme: Token süresi dolmadan önce yeni token alın
Hata Yönetimi: 401 Unauthorized hatası aldığınızda token'ı yenileyin
Güvenli Saklama: Token'ları güvenli bir şekilde saklayın (memory, secure storage)

Token Yenileme Örneği #

class MarketplaceAPIClient {
  constructor(username, password, merchantNo) {
    this.credentials = { username, password, merchantNo };
    this.token = null;
    this.tokenExpiry = null;
  }

  async ensureValidToken() {
    // Token yoksa veya süresi dolmuşsa yeni al
    if (!this.token || Date.now() >= this.tokenExpiry) {
      await this.refreshToken();
    }
    return this.token;
  }

  async refreshToken() {
    const response = await fetch(
      'https://apitest.paynkolay.com.tr/marketplace/v1/authenticate',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(this.credentials),
      }
    );

    const data = await response.json();
    this.token = data.data.token;

    // JWT'den expiry time'ı parse et
    const payload = JSON.parse(atob(this.token.split('.')[1]));
    this.tokenExpiry = payload.exp * 1000; // milisaniyeye çevir
  }

  async callAPI(endpoint, body) {
    const token = await this.ensureValidToken();

    const response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    });

    // 401 hatası alırsak token'ı yenile ve tekrar dene
    if (response.status === 401) {
      await this.refreshToken();
      return this.callAPI(endpoint, body);
    }

    return await response.json();
  }
}

Güvenlik Anahtarları #

Pazaryeri API'sinde kullanılan diğer önemli güvenlik anahtarları:

Anahtar	Açıklama	Kullanım Yeri
apiSecretKey	SX değeri - Ödeme işlemleri için kullanılır	Ödeme, Satıcı, Profil servisleri
merchantSecretKey	Ödeme işlemleri için hash hesaplamasında kullanılır	Hash hesaplama
apiSecretKey (iptal)	İptal işlemleri için özel SX değeri	İptal/İade servisleri

Bu anahtarlar Paynkolay tarafından size özel olarak verilecektir ve farklı işlemler için farklı anahtarlar kullanılmaktadır.

Sonraki Adımlar #

Token'ı aldıktan sonra:

1. Hash Hesaplama - Ödeme işlemleri için hash hesaplama
2. Ödeme Profili Oluşturma - İlk ödeme profilinizi tanımlayın
3. Satıcı Ekleme - İlk satıcınızı sisteme ekleyin