Pazaryeri Entegrasyonu

Raporlama Servisleri

İşlemlerinizi, satıcı performansını ve finansal durumu beş servisle analiz edin: işlem raporu, satıcı raporu, ödeme listesi, borç raporu ve ceza uygulama.

GetTransactionReport

Belirli bir işlemin, satıcı kırılımlarıyla birlikte detaylı raporunu getirir.

TESTPOST https://apitest.paynkolay.com.tr/marketplace/v1/transaction/report

PRODPOST https://api.paynkolay.com.tr/marketplace/v1/transaction/report

İstek — JSON

{
  "trxCode": "ORDER_12345",
  "refCode": "REF123456789",
  "apiSecretKey": "sx_value"
}

Yanıt — JSON

{
  "data": [
    {
      "mpCode": "MP12345",
      "mpOrderCode": "ORDER_12345",
      "trxType": "SALES",
      "trxDatetime": "2025-01-20T14:30:15.204156Z",
      "trxCode": "REF123456789",
      "trxCurrency": "949",
      "trxAmount": 150.00,
      "trxStatus": "SUCCESS",
      "pfCommissionRate": 2.50,
      "pfCommissionAmount": 3.75,
      "sellerTransactionList": [
        {
          "sellerName": "Ahmet Yılmaz",
          "trxAmount": 100.00,
          "trxCurrency": "TRY",
          "trxStatus": "SUCCESS",
          "mpCommissionRate": 5.00,
          "mpCommissionAmount": 5.00,
          "mpCost": 0.50,
          "trxType": "SALES",
          "withholdingTax": 0.80,
          "trxCode": "REF123456789",
          "refCode": "REF123456789"
        },
        {
          "sellerName": "Örnek Teknoloji A.Ş.",
          "trxAmount": 50.00,
          "trxCurrency": "TRY",
          "trxStatus": "SUCCESS",
          "mpCommissionRate": 7.00,
          "mpCommissionAmount": 3.50,
          "mpCost": 0.25,
          "trxType": "SALES",
          "withholdingTax": 0.40,
          "trxCode": "REF123456789",
          "refCode": "REF123456789"
        }
      ]
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS",
  "reportTime": "2025-01-20T15:00:00"
}

trxCode veya refCode'dan en az biri yeterlidir. Yanıtta ana işlem (tutar, durum, Paynkolay komisyonu) ve sellerTransactionList içinde satıcı bazlı kırılım (satıcı adı, tutar, pazaryeri komisyonu, işlem ücreti, stopaj) döner.

GetSellerTransactionReportByDate

Tarih aralığında bir satıcının tüm işlemlerini, özet istatistiklerle listeler.

TESTPOST https://apitest.paynkolay.com.tr/marketplace/v1/transaction/seller/report

PRODPOST https://api.paynkolay.com.tr/marketplace/v1/transaction/seller/report

Parametre	Tip	Zorunlu	Açıklama
from / to	String	✅	Tarih aralığı (yyyy-MM-dd)
sellerExternalId	String	✅	Satıcı external ID
apiSecretKey	String	❌	SX değeri
marketplaceCode	String	❌	Pazaryeri kodu
trxType	String	❌	Filtre: SALES, REFUND, CANCEL
trxStatus	String	❌	Filtre: SUCCESS, PENDING, FAILED

İstek — JSON

{
  "from": "2025-01-01",
  "to": "2025-01-31",
  "sellerExternalId": "SELLER_001",
  "apiSecretKey": "sx_value",
  "marketplaceCode": "MP12345",
  "trxType": "SALES",
  "trxStatus": "SUCCESS"
}

Yanıt — JSON

{
  "countSuccessTransaction": 45,
  "countFailedTransaction": 3,
  "countSuccessSalesTransaction": 40,
  "countSuccessRefundTransaction": 4,
  "countSuccessCancelTransaction": 1,
  "totalAuthAmount": 12500.00,
  "totalPfCommissionAmount": 312.50,
  "totalMpCommissionAmount": 625.00,
  "totalSellerAmount": 11562.50,
  "data": [
    {
      "sellerName": "Ahmet Yılmaz",
      "trxAmount": 250.00,
      "trxCurrency": "TRY",
      "trxStatus": "SUCCESS",
      "mpCommissionRate": 5.00,
      "mpCommissionAmount": 12.50,
      "mpCost": 0.50,
      "trxType": "SALES",
      "withholdingTax": 2.00,
      "trxCode": "ORDER_001",
      "refCode": "REF001"
    },
    {
      "sellerName": "Ahmet Yılmaz",
      "trxAmount": 180.00,
      "trxCurrency": "TRY",
      "trxStatus": "SUCCESS",
      "mpCommissionRate": 5.00,
      "mpCommissionAmount": 9.00,
      "mpCost": 0.50,
      "trxType": "SALES",
      "withholdingTax": 1.44,
      "trxCode": "ORDER_002",
      "refCode": "REF002"
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS",
  "reportTime": "2025-01-20T16:30:00"
}

Özet Alanı	Açıklama
countSuccessTransaction	Başarılı işlem sayısı
countFailedTransaction	Başarısız işlem sayısı
countSuccessSalesTransaction	Başarılı satış sayısı
countSuccessRefundTransaction	Başarılı iade sayısı
countSuccessCancelTransaction	Başarılı iptal sayısı
totalAuthAmount	Toplam onaylanan tutar
totalPfCommissionAmount	Toplam Paynkolay komisyonu
totalMpCommissionAmount	Toplam pazaryeri komisyonu
totalSellerAmount	Satıcıya kalan net tutar

GetSellerPaymentList

Satıcıya yapılan para transferlerini (hakediş ödemelerini) listeler.

TESTPOST https://apitest.paynkolay.com.tr/marketplace/v1/transaction/seller/payment-report

PRODPOST https://api.paynkolay.com.tr/marketplace/v1/transaction/seller/payment-report

İstek — JSON

{
  "from": "2025-01-01",
  "to": "2025-01-31",
  "sellerExternalId": "SELLER_001",
  "apiSecretKey": "sx_value",
  "marketplaceCode": "MP12345"
}

Yanıt — JSON

{
  "data": [
    {
      "sellerName": "Ahmet Yılmaz",
      "sellerExternalId": "SELLER_001",
      "trxAmount": 5000.00,
      "description": "Haftalık Hakediş Ödemesi - Hafta 3",
      "currency": "TRY",
      "transferDate": "2025-01-20",
      "eftOutDate": "2025-01-20"
    },
    {
      "sellerName": "Ahmet Yılmaz",
      "sellerExternalId": "SELLER_001",
      "trxAmount": 4500.00,
      "description": "Haftalık Hakediş Ödemesi - Hafta 2",
      "currency": "TRY",
      "transferDate": "2025-01-13",
      "eftOutDate": "2025-01-13"
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS",
  "reportTime": "2025-01-20T17:00:00"
}

Yanıt Alanı	Açıklama
trxAmount	Transfer tutarı
description	Transfer açıklaması (ör. "Haftalık Hakediş Ödemesi")
transferDate	Transfer tarihi
eftOutDate	EFT çıkış tarihi

GetSellerDebtReport

Satıcının borç durumunu gösterir; uygulanan cezalar da burada listelenir.

TESTPOST https://apitest.paynkolay.com.tr/marketplace/v1/transaction/seller/debt-report

PRODPOST https://api.paynkolay.com.tr/marketplace/v1/transaction/seller/debt-report

Bu serviste tarih formatı datetime'dır: yyyy-MM-ddTHH:mm (ör. 2025-01-31T23:59).

İstek — JSON

{
  "from": "2025-01-01T00:00",
  "to": "2025-01-31T23:59",
  "sellerExternalId": "SELLER_001",
  "marketplaceCode": "MP12345",
  "apiSecretKey": "sx_value"
}

Yanıt — JSON

{
  "data": [
    {
      "sellerName": "Ahmet Yılmaz",
      "debtAmount": 150.00,
      "trxCurrency": "TRY",
      "debtCreateDate": "2025-01-15T14:30:00",
      "debtUpdateDate": "2025-01-20T10:00:00",
      "debtStatus": true
    }
  ],
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS",
  "reportTime": "2025-01-20T18:00:00"
}

Yanıt Alanı	Açıklama
debtAmount	Borç tutarı
debtCreateDate / debtUpdateDate	Borcun oluşturulma / güncellenme zamanı
debtStatus	true = aktif borç, false = kapatılmış

ApplyPenalty

Satıcıya ceza/borç tanımlar (iade edilmeyen kargo, hasarlı ürün, sözleşme ihlali…). Ceza satıcının borç bakiyesine eklenir ve ödeme günü geldiğinde hakedişinden mahsup edilir.

TESTPOST https://apitest.paynkolay.com.tr/marketplace/v1/penalty

PRODPOST https://api.paynkolay.com.tr/marketplace/v1/penalty

İstek — JSON

{
  "sellerExternalId": "SELLER_001",
  "amount": "2000.0",
  "description": "İade edilmeyen kargo cezası",
  "debtDate": "2026-08-03",
  "apiSecretKey": "sx_value"
}

Parametre	Tip	Zorunlu	Açıklama
sellerExternalId	String	✅	Ceza uygulanacak satıcı — aktif olmalıdır
amount	String	✅	Ceza/borç tutarı
description	String	✅	Ceza açıklaması
debtDate	String	✅	Borç tarihi (yyyy-MM-dd) — aynı satıcıya tarihsiz aktif ceza yalnızca bir kez tanımlanabilir
apiSecretKey	String	✅	Satış SX değeri

Başarılı Yanıt

{
  "success": true,
  "message": "İşlem başarılı"
}

Hata Yanıtı — HTTP 400

{
  "success": false,
  "message": "Aktif Satıcı Bulunamadı!"
}

Uygulanan cezayı GetSellerDebtReport ile doğrulayabilirsiniz.

Dashboard ve Excel Örnekleri

Raporlama servislerini bir araya getiren iki çalışır örnek:

class MarketplaceDashboard {
  async getOverview(from, to) {
    const allSellers = await this.getAllSellers();

    const overview = {
      totalSellers: allSellers.data.length,
      activeSellers: allSellers.data.filter(s => s.active).length,
      totalRevenue: 0,
      totalCommission: 0,
      totalTransactions: 0,
      sellerReports: []
    };

    for (const seller of allSellers.data) {
      const report = await getSellerTransactionReportByDate({
        from,
        to,
        sellerExternalId: seller.sellerExternalId,
        apiSecretKey: this.apiSecretKey
      });

      overview.totalRevenue += report.totalAuthAmount;
      overview.totalCommission += report.totalMpCommissionAmount;
      overview.totalTransactions += report.countSuccessTransaction;

      overview.sellerReports.push({
        sellerId: seller.sellerExternalId,
        sellerName: seller.nameSurname,
        sales: report.countSuccessSalesTransaction,
        revenue: report.totalAuthAmount,
        commission: report.totalMpCommissionAmount
      });
    }

    // Satıcıları ciroya göre sırala / Sort sellers by revenue
    overview.sellerReports.sort((a, b) => b.revenue - a.revenue);

    return overview;
  }

  displayDashboard(overview) {
    console.log('\n📊 MARKETPLACE DASHBOARD\n');
    console.log(`Total Sellers: ${overview.totalSellers}`);
    console.log(`Active Sellers: ${overview.activeSellers}`);
    console.log(`Total Revenue: ${overview.totalRevenue.toFixed(2)} TL`);
    console.log(`Total Commission: ${overview.totalCommission.toFixed(2)} TL`);
    console.log(`Total Transactions: ${overview.totalTransactions}\n`);

    console.log('🏆 TOP SELLERS:\n');
    overview.sellerReports.slice(0, 10).forEach((seller, index) => {
      console.log(
        `${index + 1}. ${seller.sellerName}: ` +
        `${seller.revenue.toFixed(2)} TL (${seller.sales} sales)`
      );
    });
  }
}

// Kullanım
const dashboard = new MarketplaceDashboard();
const overview = await dashboard.getOverview('2025-01-01', '2025-01-31');
dashboard.displayDashboard(overview);

const ExcelJS = require('exceljs');

async function exportSellerReport(sellerExternalId, from, to) {
  const report = await getSellerTransactionReportByDate({
    from,
    to,
    sellerExternalId,
    apiSecretKey: process.env.API_SECRET_KEY
  });

  const workbook = new ExcelJS.Workbook();
  const worksheet = workbook.addWorksheet('İşlem Raporu');

  // Başlıklar / Headers
  worksheet.columns = [
    { header: 'İşlem Kodu', key: 'trxCode', width: 20 },
    { header: 'Tarih', key: 'date', width: 15 },
    { header: 'Tutar', key: 'amount', width: 12 },
    { header: 'Komisyon', key: 'commission', width: 12 },
    { header: 'Stopaj', key: 'tax', width: 12 },
    { header: 'Net', key: 'net', width: 12 },
    { header: 'Durum', key: 'status', width: 12 }
  ];

  // Veriler / Data
  report.data.forEach(trx => {
    worksheet.addRow({
      trxCode: trx.trxCode,
      date: trx.trxDate,
      amount: trx.trxAmount,
      commission: trx.mpCommissionAmount,
      tax: trx.withholdingTax,
      net: trx.trxAmount - trx.mpCommissionAmount - trx.withholdingTax,
      status: trx.trxStatus
    });
  });

  // Stil / Style
  worksheet.getRow(1).font = { bold: true };

  // Kaydet / Save
  await workbook.xlsx.writeFile(`seller_report_${sellerExternalId}.xlsx`);
}

Bu sayfa yardımcı oldu mu?

Son güncelleme: 10 Eylül 2026