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	❌	Pay N Kolay referans kodu
`apiSecretKey`	String	✅	SX değeri

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	Pay N Kolay referans kodu
`trxCurrency`	String	Para birimi kodu
`trxAmount`	BigDecimal	Toplam işlem tutarı
`trxStatus`	String	İşlem durumu
`pfCommissionRate`	BigDecimal	Pay N Kolay komisyon oranı
`pfCommissionAmount`	BigDecimal	Pay N Kolay 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 Pay N Kolay 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"
}

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
    apiSecretKey: process.env.API_SECRET_KEY,
    trxType: 'SALES',
    trxStatus: 'SUCCESS'
  });

  console.log('Günlük Özet:');
  console.log(`Toplam Satış: ${report.countSuccessSalesTransaction}`);
  console.log(`Toplam Tutar: ${report.totalAuthAmount} TL`);
  console.log(`Komisyon: ${report.totalMpCommissionAmount} TL`);
  console.log(`Net Kazanç: ${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:\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: ${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 borç`);

      // Satıcıyı bilgilendir
      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
    overview.sellerReports.sort((a, b) => b.revenue - a.revenue);

    return overview;
  }

  displayDashboard(overview) {
    console.log('\n📊 PAZARYERI DASHBOARD\n');
    console.log(`Toplam Satıcı: ${overview.totalSellers}`);
    console.log(`Aktif Satıcı: ${overview.activeSellers}`);
    console.log(`Toplam Ciro: ${overview.totalRevenue.toFixed(2)} TL`);
    console.log(`Toplam Komisyon: ${overview.totalCommission.toFixed(2)} TL`);
    console.log(`Toplam İşlem: ${overview.totalTransactions}\n`);

    console.log('🏆 EN İYİ SATICILAR:\n');
    overview.sellerReports.slice(0, 10).forEach((seller, index) => {
      console.log(
        `${index + 1}. ${seller.sellerName}: ` +
        `${seller.revenue.toFixed(2)} TL (${seller.sales} satış)`
      );
    });
  }
}

// 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
  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
  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
  worksheet.getRow(1).font = { bold: true };

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

Sonraki Adımlar

Raporlama sistemini kurduktan sonra:

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