Satıcı Yönetimi

Satıcı Yönetimi Nedir? #

Satıcı yönetimi servisleri ile pazaryerinize bağlı alt satıcıları sisteme ekleyebilir, güncelleyebilir, sorgulayabilir ve silebilirsiniz.

Her satıcı bir ödeme profili ile ilişkilendirilir ve bu profile göre komisyon oranları, ödeme günleri belirlenir.

Satıcı Tipleri #

Pazaryeri sisteminde üç tip satıcı tanımlanabilir:

Tip	Kod	Açıklama	Kimlik
Gerçek Kişi	1	Bireysel satıcılar	11 haneli TCKN
Şahıs Şirketi	2	Tek kişilik şirketler	11 haneli TCKN
Tüzel Kişi Şirketi	3	Limited, Anonim şirketler	10 haneli VKN

Satıcı Servisleri #

CreateSeller - Yeni satıcı oluşturma
GetSellerById - Satıcı bilgilerini sorgulama
UpdateSeller - Satıcı bilgilerini güncelleme
DeleteSellerById - Satıcı silme
GetAllSellerByApiSecretKey - Tüm satıcıları listeleme

1. CreateSeller #

Yeni bir satıcı oluşturur.

Endpoint #

TEST:

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

PROD:

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

İstek Parametreleri #

{
  "sellerExternalId": "SELLER_001",
  "nameSurname": "Ahmet Yılmaz",
  "sellerType": 1,
  "tckn": "12345678901",
  "vkn": null,
  "birthDate": "15.05.1985",
  "taxOffice": "Kadıköy",
  "contactPerson": "Ahmet Yılmaz",
  "email": "ahmet@example.com",
  "phoneNumber": "5551234567",
  "city": "34",
  "address": "Atatürk Cad. No:123 Kadıköy",
  "iban": "TR330006100519786457841326",
  "accountHolder": "Ahmet Yılmaz",
  "apiSecretKey": "sx_value_here",
  "active": true,
  "mpPaymentProfileExternalId": "PREMIUM_PROFILE"
}

Parametre Detayları #

Parametre	Tip	Zorunlu	Açıklama
sellerExternalId	String	✅	Tekil dış ID - Kendi sisteminizdeki satıcı ID'si
nameSurname	String	✅	Ad Soyad (Gerçek/Şahıs) veya Şirket Adı (Tüzel)
sellerType	Integer	✅	1=Gerçek Kişi, 2=Şahıs Şirketi, 3=Tüzel Kişi
tckn	String	✅*	11 haneli TCKN (Tip 1 ve 2 için zorunlu)
vkn	String	✅*	10 haneli VKN (Tip 3 için zorunlu)
birthDate	String	❌	Doğum tarihi (dd.MM.yyyy formatında)
taxOffice	String	❌	Vergi dairesi adı
contactPerson	String	❌	İrtibat kişisi ad-soyad
email	String	❌	E-posta adresi
phoneNumber	String	❌	Cep telefonu (5551234567 formatında)
city	String	❌	Şehir plaka kodu (ör: 34, 06, 35)
address	String	❌	Adres bilgisi
iban	String	✅	IBAN numarası (TR ile başlamalı)
accountHolder	String	❌	Hesap sahibi adı (nameSurname ile aynı olmalı)
apiSecretKey	String	✅	Pazaryerine ait SX değeri
active	Boolean	❌	Satıcı aktif mi? (varsayılan: true)
mpPaymentProfileExternalId	String	✅	Atanacak ödeme profili ID'si

Örnek İstekler #

Gerçek Kişi Satıcı #

{
  "sellerExternalId": "GK_001",
  "nameSurname": "Ayşe Demir",
  "sellerType": 1,
  "tckn": "98765432101",
  "birthDate": "20.03.1990",
  "taxOffice": "Beşiktaş",
  "contactPerson": "Ayşe Demir",
  "email": "ayse@example.com",
  "phoneNumber": "5559876543",
  "city": "34",
  "address": "Barbaros Bulvarı No:45 Beşiktaş",
  "iban": "TR120006200011122233344455",
  "accountHolder": "Ayşe Demir",
  "apiSecretKey": "sx_value",
  "active": true,
  "mpPaymentProfileExternalId": "STANDARD_PROFILE"
}

Tüzel Kişi Şirketi #

{
  "sellerExternalId": "COMPANY_001",
  "nameSurname": "Örnek Teknoloji A.Ş.",
  "sellerType": 3,
  "vkn": "1234567890",
  "taxOffice": "Kozyatağı",
  "contactPerson": "Mehmet Kaya",
  "email": "info@ornekteknoloji.com",
  "phoneNumber": "5551112233",
  "city": "34",
  "address": "Atatürk Mah. Teknoloji Cad. No:100 Kadıköy",
  "iban": "TR450006400000115638974521",
  "accountHolder": "Örnek Teknoloji A.Ş.",
  "apiSecretKey": "sx_value",
  "active": true,
  "mpPaymentProfileExternalId": "PREMIUM_PROFILE"
}

Yanıt #

{
  "data": {
    "sellerExternalId": "SELLER_001",
    "active": true,
    "nameSurname": "Ahmet Yılmaz",
    "sellerType": "Gerçek Kişi",
    "tckn": "12345678901",
    "birthDate": "1985-05-15",
    "vkn": null,
    "contactPerson": "Ahmet Yılmaz",
    "phoneNumber": "5551234567",
    "city": "34",
    "address": "Atatürk Cad. No:123 Kadıköy",
    "iban": "TR330006100519786457841326",
    "accountHolder": "Ahmet Yılmaz",
    "paymentProfile": {
      "profileExternalId": "PREMIUM_PROFILE",
      "marketplaceCode": "MP12345",
      "name": "Premium Satıcı Profili",
      "mpCommissionRate": 5.00,
      "mpCost": 0.50,
      "paymentDay": "per",
      "valorDateCount": 1,
      "active": true,
      "createDate": "2025-01-15T10:30:00Z",
      "updateDate": "2025-01-15T10:30:00Z"
    },
    "marketplaceCode": "MP12345",
    "taxOffice": "Kadıköy",
    "createDate": "2025-01-20T14:25:00Z",
    "updateDate": "2025-01-20T14:25:00Z",
    "email": "ahmet@example.com"
  },
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

2. GetSellerById #

Belirli bir satıcının detay bilgilerini getirir.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/seller/get

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/seller/get

İstek #

{
  "sellerExternalId": "SELLER_001"
}

Yanıt #

Yanıt formatı CreateSeller ile aynıdır. Satıcının güncel bilgileri ve bağlı olduğu ödeme profili bilgileri döner.

3. UpdateSeller #

Mevcut bir satıcının bilgilerini günceller.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/seller/update

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/seller/update

İstek #

{
  "sellerExternalId": "SELLER_001",
  "nameSurname": "Ahmet Yılmaz",
  "sellerType": 1,
  "tckn": "12345678901",
  "birthDate": "15.05.1985",
  "taxOffice": "Kadıköy",
  "contactPerson": "Ahmet Yılmaz",
  "email": "ahmet.yeni@example.com",
  "phoneNumber": "5559998877",
  "city": "34",
  "address": "Yeni Adres Bilgisi",
  "iban": "TR330006100519786457841326",
  "accountHolder": "Ahmet Yılmaz",
  "apiSecretKey": "sx_value",
  "active": true,
  "mpPaymentProfileExternalId": "STANDARD_PROFILE"
}

warning

Yanıt #

CreateSeller ile aynı formatta güncellenmiş satıcı bilgileri döner.

4. DeleteSellerById #

Bir satıcıyı sistemden siler.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/seller/delete

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/seller/delete

İstek #

{
  "sellerExternalId": "SELLER_001"
}

Yanıt #

{
  "data": null,
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

warning

5. GetAllSellerByApiSecretKey #

Pazaryerine ait tüm satıcıları listeler.

Endpoint #

TEST:

POST https://apitest.paynkolay.com.tr/marketplace/v1/seller/sellers

PROD:

POST https://api.paynkolay.com.tr/marketplace/v1/seller/sellers

İstek #

{
  "apiSecretKey": "sx_value",
  "active": true
}

Parametre	Tip	Zorunlu	Açıklama
apiSecretKey	String	✅	Pazaryerine ait SX değeri
active	Boolean	❌	true=sadece aktif, false=sadece pasif, null=tümü

Yanıt #

{
  "data": [
    {
      "sellerExternalId": "SELLER_001",
      "active": true,
      "nameSurname": "Ahmet Yılmaz",
      "sellerType": "Gerçek Kişi",
      "tckn": "12345678901",
      "birthDate": "1985-05-15",
      "paymentProfile": {
        "profileExternalId": "PREMIUM_PROFILE",
        "name": "Premium Satıcı Profili",
        "mpCommissionRate": 5.00
      },
      "email": "ahmet@example.com"
    },
    {
      "sellerExternalId": "COMPANY_001",
      "active": true,
      "nameSurname": "Örnek Teknoloji A.Ş.",
      "sellerType": "Tüzel Kişi",
      "vkn": "1234567890",
      "paymentProfile": {
        "profileExternalId": "STANDARD_PROFILE",
        "name": "Standart Profil",
        "mpCommissionRate": 7.00
      },
      "email": "info@ornekteknoloji.com"
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS"
}

Kullanım Senaryoları #

Senaryo 1: Toplu Satıcı Ekleme #

const sellers = [
  {
    sellerExternalId: "SELLER_001",
    nameSurname: "Ahmet Yılmaz",
    sellerType: 1,
    tckn: "12345678901",
    iban: "TR330006100519786457841326",
    mpPaymentProfileExternalId: "PREMIUM_PROFILE"
  },
  {
    sellerExternalId: "SELLER_002",
    nameSurname: "Ayşe Demir",
    sellerType: 1,
    tckn: "98765432101",
    iban: "TR120006200011122233344455",
    mpPaymentProfileExternalId: "STANDARD_PROFILE"
  }
];

for (const seller of sellers) {
  await createSeller({
    ...seller,
    apiSecretKey: process.env.API_SECRET_KEY,
    contactPerson: seller.nameSurname,
    accountHolder: seller.nameSurname,
    active: true
  });
}

Senaryo 2: Satıcı Profil Değişikliği #

// Satıcının performansına göre premium profile yükselt
async function upgradeSellerToPremium(sellerExternalId) {
  // Mevcut satıcı bilgilerini al
  const seller = await getSeller(sellerExternalId);

  // Premium profile güncelle
  await updateSeller({
    ...seller.data,
    mpPaymentProfileExternalId: "PREMIUM_PROFILE"
  });

  console.log(`${sellerExternalId} premium profile yükseltildi`);
}

Senaryo 3: Aktif Satıcıları Listeleme ve Raporlama #

async function getActiveSellersReport() {
  const response = await getAllSellers({
    apiSecretKey: process.env.API_SECRET_KEY,
    active: true
  });

  const report = response.data.map(seller => ({
    id: seller.sellerExternalId,
    name: seller.nameSurname,
    type: seller.sellerType,
    commission: seller.paymentProfile.mpCommissionRate,
    email: seller.email
  }));

  console.table(report);
  return report;
}

Örnek Kod Bütünlüğü #

const axios = require('axios');

class SellerManager {
  constructor(apiSecretKey, baseURL) {
    this.apiSecretKey = apiSecretKey;
    this.baseURL = baseURL;
  }

  async createSeller(sellerData) {
    const response = await axios.post(
      `${this.baseURL}/seller`,
      {
        ...sellerData,
        apiSecretKey: this.apiSecretKey
      }
    );
    return response.data;
  }

  async getSeller(sellerExternalId) {
    const response = await axios.post(
      `${this.baseURL}/seller/get`,
      { sellerExternalId }
    );
    return response.data;
  }

  async updateSeller(sellerData) {
    const response = await axios.post(
      `${this.baseURL}/seller/update`,
      {
        ...sellerData,
        apiSecretKey: this.apiSecretKey
      }
    );
    return response.data;
  }

  async deleteSeller(sellerExternalId) {
    const response = await axios.post(
      `${this.baseURL}/seller/delete`,
      { sellerExternalId }
    );
    return response.data;
  }

  async listSellers(activeOnly = null) {
    const response = await axios.post(
      `${this.baseURL}/seller/sellers`,
      {
        apiSecretKey: this.apiSecretKey,
        active: activeOnly
      }
    );
    return response.data;
  }
}

// Kullanım
const manager = new SellerManager(
  process.env.API_SECRET_KEY,
  'https://apitest.paynkolay.com.tr/marketplace/v1'
);

// Satıcı oluştur
const newSeller = await manager.createSeller({
  sellerExternalId: "SELLER_123",
  nameSurname: "Test Satıcı",
  sellerType: 1,
  tckn: "12345678901",
  iban: "TR330006100519786457841326",
  accountHolder: "Test Satıcı",
  contactPerson: "Test Satıcı",
  mpPaymentProfileExternalId: "PREMIUM_PROFILE",
  active: true
});

En İyi Uygulamalar #

1. IBAN Doğrulama #

function validateIBAN(iban) {
  // TR ile başlamalı ve 26 karakter olmalı
  if (!iban.startsWith('TR') || iban.length !== 26) {
    throw new Error('Geçersiz IBAN formatı');
  }

  // IBAN mod-97 kontrolü
  const rearranged = iban.substring(4) + iban.substring(0, 4);
  const numericIBAN = rearranged.replace(/[A-Z]/g, (char) =>
    char.charCodeAt(0) - 55
  );

  // Büyük sayılarla çalışmak için
  const remainder = BigInt(numericIBAN) % 97n;

  if (remainder !== 1n) {
    throw new Error('IBAN doğrulama hatası');
  }

  return true;
}

2. TCKN Doğrulama #

function validateTCKN(tckn) {
  if (tckn.length !== 11) return false;

  const digits = tckn.split('').map(Number);

  // İlk hane 0 olamaz
  if (digits[0] === 0) return false;

  // 10. hane kontrolü
  const sum10 = (
    (digits[0] + digits[2] + digits[4] + digits[6] + digits[8]) * 7 -
    (digits[1] + digits[3] + digits[5] + digits[7])
  ) % 10;

  if (sum10 !== digits[9]) return false;

  // 11. hane kontrolü
  const sum11 = digits.slice(0, 10).reduce((a, b) => a + b) % 10;

  return sum11 === digits[10];
}

3. VKN Doğrulama #

function validateVKN(vkn) {
  if (vkn.length !== 10) return false;

  const v = vkn.split('').map(Number);
  let sum = 0;

  for (let i = 0; i < 9; i++) {
    let digit = (v[i] + (9 - i)) % 10;
    sum += (digit * Math.pow(2, 9 - i)) % 9;
    if (digit !== 0 && (digit * Math.pow(2, 9 - i)) % 9 === 0) sum += 9;
  }

  return (10 - (sum % 10)) % 10 === v[9];
}

Sonraki Adımlar #

Satıcılarınızı ekledikten sonra:

1. Ödeme İşlemleri - Satıcılardan ödeme almaya başlayın
2. Raporlama - Satıcı bazlı raporlar alın
3. Ödeme Değişiklikleri - İade ve iptal işlemleri