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 Pay N Kolay 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

1. Token’ı Cache’leyin: Her API isteğinde yeni token almak yerine, mevcut token’ı kullanın
2. Token Yenileme: Token süresi dolmadan önce yeni token alın
3. Hata Yönetimi: 401 Unauthorized hatası aldığınızda token’ı yenileyin
4. 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

Bilgi

Bu anahtarlar Pay N Kolay 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