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"
}

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"
}

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:

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