Raporlama Servisleri

Raporlama Genel Bakış #

Pazaryeri raporlama servisleri ile işlemlerinizi, satıcılarınızın performansını ve finansal durumlarını detaylı olarak analiz edebilirsiniz.

Bu sayfada aşağıdaki raporlama servislerini öğreneceksiniz:

GetTransactionReport - İşlem bazlı raporlama
GetSellerTransactionReportByDate - Satıcı ve tarih bazlı raporlama
GetSellerPaymentList - Satıcı ödeme listesi
GetSellerDebtReport - Satıcı borç raporu

1. GetTransactionReport #

Belirli bir işlemin detaylı raporunu getirir.

Endpoint #

TEST:

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

PROD:

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

İstek #

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

Parametre	Tip	Zorunlu	Açıklama
trxCode	String	❌	Sizin işlem kodunuz
refCode	String	❌	Paynkolay referans kodu
apiSecretKey	String	✅	SX değeri

`trxCode` veya `refCode`'dan en az birini göndermeniz yeterlidir.

Yanıt #

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

Yanıt Parametreleri #

Ana İşlem Bilgileri #

Parametre	Tip	Açıklama
mpCode	String	Pazaryeri kodu
mpOrderCode	String	Sizin gönderdiğiniz işlem kodu
trxType	String	İşlem tipi (SALES, REFUND, CANCEL)
trxDatetime	String	İşlem tarihi (ISO 8601)
trxCode	String	Paynkolay referans kodu
trxCurrency	String	Para birimi kodu
trxAmount	BigDecimal	Toplam işlem tutarı
trxStatus	String	İşlem durumu
pfCommissionRate	BigDecimal	Paynkolay komisyon oranı
pfCommissionAmount	BigDecimal	Paynkolay komisyon tutarı

Satıcı İşlem Bilgileri #

Parametre	Tip	Açıklama
sellerName	String	Satıcı adı
trxAmount	BigDecimal	Satıcının işlem tutarı
mpCommissionRate	BigDecimal	Pazaryeri komisyon oranı
mpCommissionAmount	BigDecimal	Pazaryeri komisyon tutarı
mpCost	BigDecimal	İşlem ücreti
withholdingTax	BigDecimal	Stopaj tutarı

2. GetSellerTransactionReportByDate #

Belirli bir tarih aralığında satıcının tüm işlemlerini listeler.

Endpoint #

TEST:

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

PROD:

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

İstek #

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

Parametre	Tip	Zorunlu	Açıklama
from	String	✅	Başlangıç tarihi (yyyy-MM-dd)
to	String	✅	Bitiş tarihi (yyyy-MM-dd)
sellerExternalId	String	✅	Satıcı external ID
apiSecretKey	String	❌	SX değeri
marketplaceCode	String	❌	Pazaryeri kodu
trxType	String	❌	İşlem tipi filtresi (SALES, REFUND, CANCEL)
trxStatus	String	❌	Durum filtresi (SUCCESS, PENDING, FAILED)

Yanıt #

{
  "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 İstatistikler #

Parametre	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

3. GetSellerPaymentList #

Satıcıya yapılan ödeme transferlerini listeler.

Endpoint #

TEST:

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

PROD:

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

İstek #

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

Yanıt #

{
  "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 Parametreleri #

Parametre	Tip	Açıklama
sellerName	String	Satıcı adı
sellerExternalId	String	Satıcı external ID
trxAmount	BigDecimal	Transfer tutarı
description	String	Transfer açıklaması
currency	String	Para birimi
transferDate	String	Transfer tarihi
eftOutDate	String	EFT çıkış tarihi

4. GetSellerDebtReport #

Satıcının borç durumunu gösterir.

Endpoint #

TEST:

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

PROD:

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

İstek #

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

Bu serviste tarih formatı yyyy-MM-ddTHH:mm şeklindedir (datetime).

Yanıt #

{
  "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 Parametreleri #

Parametre	Tip	Açıklama
sellerName	String	Satıcı adı
debtAmount	BigDecimal	Borç tutarı
trxCurrency	String	Para birimi
debtCreateDate	String	Borç oluşturulma tarihi
debtUpdateDate	String	Borç güncellenme tarihi
debtStatus	Boolean	Borç aktif mi? (true=aktif, false=kapalı)

Örnek Kullanım Senaryoları #

Senaryo 1: Günlük Satış Raporu #

async function getDailySalesReport(date) {
  const report = await getSellerTransactionReportByDate({
    from: date,
    to: date,
    sellerExternalId: 'ALL',  // Tüm satıcılar / All sellers
    apiSecretKey: process.env.API_SECRET_KEY,
    trxType: 'SALES',
    trxStatus: 'SUCCESS'
  });

  console.log('Günlük Özet / Daily Summary:');
  console.log(`Toplam Satış / Total Sales: ${report.countSuccessSalesTransaction}`);
  console.log(`Toplam Tutar / Total Amount: ${report.totalAuthAmount} TL`);
  console.log(`Komisyon / Commission: ${report.totalMpCommissionAmount} TL`);
  console.log(`Net Kazanç / Net Profit: ${report.totalSellerAmount} TL`);

  return report;
}

Senaryo 2: Satıcı Performans Analizi #

async function analyzeSellerPerformance(sellerExternalId, month) {
  const startDate = `${month}-01`;
  const endDate = new Date(month + '-01');
  endDate.setMonth(endDate.getMonth() + 1);
  endDate.setDate(0);
  const lastDay = endDate.toISOString().split('T')[0];

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

  const performance = {
    seller: sellerExternalId,
    period: month,
    totalSales: report.countSuccessSalesTransaction,
    totalRefunds: report.countSuccessRefundTransaction,
    revenue: report.totalSellerAmount,
    commission: report.totalMpCommissionAmount,
    refundRate: (report.countSuccessRefundTransaction / report.countSuccessSalesTransaction * 100).toFixed(2) + '%'
  };

  console.table(performance);
  return performance;
}

Senaryo 3: Ödeme Takibi #

async function trackSellerPayments(sellerExternalId) {
  const payments = await getSellerPaymentList({
    from: '2025-01-01',
    to: '2025-12-31',
    sellerExternalId,
    apiSecretKey: process.env.API_SECRET_KEY
  });

  console.log(`\n${sellerExternalId} - Ödeme Geçmişi / Payment History:\n`);

  payments.data.forEach(payment => {
    console.log(`${payment.transferDate}: ${payment.trxAmount} TL - ${payment.description}`);
  });

  const totalPaid = payments.data.reduce((sum, p) => sum + p.trxAmount, 0);
  console.log(`\nToplam Ödenen / Total Paid: ${totalPaid} TL`);

  return payments;
}

Senaryo 4: Borç Kontrolü #

async function checkSellerDebts() {
  const sellers = await getAllSellers();

  for (const seller of sellers.data) {
    const debtReport = await getSellerDebtReport({
      from: '2025-01-01T00:00',
      to: new Date().toISOString().slice(0, 16),
      sellerExternalId: seller.sellerExternalId,
      apiSecretKey: process.env.API_SECRET_KEY
    });

    const activeDebts = debtReport.data.filter(d => d.debtStatus === true);

    if (activeDebts.length > 0) {
      const totalDebt = activeDebts.reduce((sum, d) => sum + d.debtAmount, 0);

      console.log(`⚠️ ${seller.nameSurname}: ${totalDebt} TL debt`);

      // Satıcıyı bilgilendir / Notify seller
      await notifySellerAboutDebt(seller.email, totalDebt);
    }
  }
}

Dashboard Örneği #

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);

Excel Export Örneği #

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`);
}

Sonraki Adımlar #

Raporlama sistemini kurduktan sonra:

1. Ödeme İşlemleri - Yeni ödemeler alın
2. Satıcı Yönetimi - Satıcı ekleyin ve yönetin
3. Ödeme Profili - Profilleri optimize edin