BulutTahsilat Bank Payment Web Service Client SDK

An unofficial TypeScript client SDK for the BulutTahsilat Bank Payment Web Service.

A comprehensive TypeScript client SDK for the BulutTahsilat Bank Payment Web Service. This library provides type-safe access to all SOAP operations with a modern, intuitive API.

Features

• 🚀 TypeScript Client SDK - Type-safe API client with full IntelliSense support
• 🧪 Comprehensive Coverage - 40+ methods covering all SOAP service endpoints
• ⚡ Modern API - Promise-based with async/await syntax
• 🔐 Automatic Authentication - Configure once, use everywhere
• 📝 Full Type Definitions - Catch errors at compile time
• 🛡️ Error Handling - Proper SOAP fault detection and reporting
• 🔍 Debug Mode - Request/response logging for development

Installation

Install the SDK using your preferred package manager:

pnpm add @muhammedaksam/bulut-tahsilat-node

Or with npm:

npm install @muhammedaksam/bulut-tahsilat-node

Or with yarn:

yarn add @muhammedaksam/bulut-tahsilat-node

Quick Start

import { BankPaymentServiceClient, PaymentStatusType } from '@muhammedaksam/bulut-tahsilat-node';

// Initialize the client
const client = new BankPaymentServiceClient({
  userName: 'your-username',
  password: 'your-password',
  firmCode: 'your-firm-code',
  firmAPICode: 'your-firm-api-code',
});

// Get bank payment list
const payments = await client.getBankPaymentList({
  paymentStatusTypeID: PaymentStatusType.Waiting,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

console.log(payments);

Configuration

Client Options

interface ClientConfig {
  /** Username for authentication (required) */
  userName: string;

  /** Password for authentication (required) */
  password: string;

  /** Firm code for operations requiring firmCode */
  firmCode?: string;

  /** Firm API code for operations requiring firmAPICode */
  firmAPICode?: string;

  /** Base URL of the SOAP service (default: https://ws.buluttahsilat.com/WebService/WSBankPaymentService.asmx) */
  baseURL?: string;

  /** Request timeout in milliseconds (default: 30000) */
  timeout?: number;

  /** Enable debug logging (default: false) */
  debug?: boolean;
}

Example Configuration

const client = new BankPaymentServiceClient({
  userName: process.env.BULUT_USERNAME!,
  password: process.env.BULUT_PASSWORD!,
  firmCode: process.env.BULUT_FIRM_CODE,
  firmAPICode: process.env.BULUT_API_CODE,
  timeout: 60000,
  debug: process.env.NODE_ENV === 'development',
});

API Reference

Bank Payment Operations

getBankPaymentList

Get bank payment list filtered by status and date range.

const payments = await client.getBankPaymentList({
  paymentStatusTypeID: PaymentStatusType.Waiting,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

getBankPaymentListDebit

Get debit bank payments only.

const debitPayments = await client.getBankPaymentListDebit({
  paymentStatusTypeID: PaymentStatusType.Approved,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

getBankPaymentListAll

Get all bank payments (both credit and debit).

const allPayments = await client.getBankPaymentListAll({
  paymentStatusTypeID: PaymentStatusType.Approved,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

getBankPaymentListAllSubFirm

Get bank payments for all sub-firms, optionally filtered by tax number.

const subFirmPayments = await client.getBankPaymentListAllSubFirm({
  paymentStatusTypeID: PaymentStatusType.Waiting,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  taxNumber: '1234567890',
});

getBankPaymentListAllWithFeature

Get bank payments with additional feature fields.

const featuredPayments = await client.getBankPaymentListAllWithFeature({
  paymentStatusTypeID: PaymentStatusType.Approved,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

getBankPaymentListForCustomFields

Get bank payments including custom fields.

const customPayments = await client.getBankPaymentListForCustomFields({
  paymentStatusTypeID: PaymentStatusType.Waiting,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

getPaymentCategoryList

Get list of all payment categories.

const categories = await client.getPaymentCategoryList();

Payment Status Operations

updatePaymentStatus

Update the status of a single payment.

await client.updatePaymentStatus(
  12345, // paymentID
  PaymentStatusType.Approved
);

updatePaymentStatusWithExpCode

Update payment status using payment expense code.

const result = await client.updatePaymentStatusWithExpCode(
  12345,
  'EXP-CODE-001',
  PaymentStatusType.Approved
);

updatePaymentStatusWithIDList

Update status for multiple payments at once.

await client.updatePaymentStatusWithIDList([12345, 12346, 12347], PaymentStatusType.Approved);

updatePaymentStatusWithERPRefNo

Update payment status with ERP reference number.

await client.updatePaymentStatusWithERPRefNo(12345, PaymentStatusType.Approved, 'ERP-REF-001');

SubFirm Operations

addSubFirm

Create a new sub-firm.

import { EnumStatus } from '@muhammedaksam/bulut-tahsilat-node';

const result = await client.addSubFirm({
  subFirm: {
    FirmName: 'Test Company Ltd.',
    Address: '123 Main Street',
    County: 'District',
    CityID: 34,
    Phone: '+905551234567',
    TaxOffice: 'Tax Office Name',
    TaxNumber: '1234567890',
    AuthPersName: 'John',
    AuthPersSurname: 'Doe',
    AuthPersGSM: '+905551234567',
    AuthPersGenderID: 1,
    Status: EnumStatus.Active,
    DealerCode: 'DEALER001',
    BusinessArea: 'BA001',
    AccountingCode: 'AC001',
    ReservedField: 'Reserved',
  },
});

getSubFirmList

Get list of all sub-firms.

const subFirms = await client.getSubFirmList();

getSubFirmInfo

Get details of a specific sub-firm.

const info = await client.getSubFirmInfo('PAYMENT-EXP-CODE');

updateSubFirm

Update an existing sub-firm.

await client.updateSubFirm({
  paymentExpCode: 'PAYMENT-EXP-CODE',
  subFirm: {
    FirmName: 'Updated Company Name',
    // ... other fields
  },
});

addSubFirmIBAN / deleteSubFirmIBAN

Manage IBANs for a sub-firm.

// Add IBAN
await client.addSubFirmIBAN({
  paymentExpCode: 'PAYMENT-EXP-CODE',
  iban: 'TR330006100519786457841326',
  bankCode: '0001',
});

// Delete IBAN
await client.deleteSubFirmIBAN({
  paymentExpCode: 'PAYMENT-EXP-CODE',
  iban: 'TR330006100519786457841326',
  bankCode: '0001',
});

addSubFirmVKN / deleteSubFirmVKN

Manage tax numbers (VKN) for a sub-firm.

// Add VKN
await client.addSubFirmVKN({
  paymentExpCode: 'PAYMENT-EXP-CODE',
  vkn: '1234567890',
  name: 'John',
  surname: 'Doe',
});

// Delete VKN
await client.deleteSubFirmVKN({
  paymentExpCode: 'PAYMENT-EXP-CODE',
  vkn: '1234567890',
});

getSubFirmPaymentChannel

Get payment channel configuration for a sub-firm.

const channel = await client.getSubFirmPaymentChannel('PAYMENT-EXP-CODE');
console.log(channel.IBANList);
console.log(channel.VKNList);
console.log(channel.FormulaList);

deleteAllMatchingCriteria

Delete all matching criteria for a sub-firm.

const result = await client.deleteAllMatchingCriteria('PAYMENT-EXP-CODE');

Bank Balance Operations

getFirmBankBalance

Get current bank balance for all accounts or a specific IBAN.

// All accounts
const balance = await client.getFirmBankBalance();

// Specific IBAN
const ibanBalance = await client.getFirmBankBalance('TR330006100519786457841326');

getFirmBankBalanceSubFirm

Get bank balance for a sub-firm.

const balance = await client.getFirmBankBalanceSubFirm(
  'TR330006100519786457841326',
  '1234567890' // tax number
);

getFirmBankDailyBalance

Get bank balance for a specific date.

const dailyBalance = await client.getFirmBankDailyBalance(
  'TR330006100519786457841326',
  new Date('2024-01-15')
);

POS Payment Operations

getPosPaymentList

Get POS payment transactions.

const posPayments = await client.getPosPaymentList({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

getPosPaymentListWithValorDate

Get POS payments filtered by valor date.

const payments = await client.getPosPaymentListWithValorDate({
  valorStartDate: new Date('2024-01-01'),
  valorEndDate: new Date('2024-01-31'),
});

getPosPaymentListWithEndOfDay

Get POS payments filtered by end of day date.

const payments = await client.getPosPaymentListWithEndOfDay({
  endOfDayStartDate: new Date('2024-01-01'),
  endOfDayEndDate: new Date('2024-01-31'),
});

getPosPaymentSUM / getValorPaymentSUM

Get sum of POS payments.

const sum = await client.getPosPaymentSUM({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

const valorSum = await client.getValorPaymentSUM({
  valorStartDate: new Date('2024-01-01'),
  valorEndDate: new Date('2024-01-31'),
});

getPosPaymentListGreaterThanID

Incrementally fetch POS payments (for pagination/sync).

const newPayments = await client.getPosPaymentListGreaterThanID({
  posPaymentID: 1000,
});

getPosReturnList

Get POS return transactions.

const returns = await client.getPosReturnList({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

Other Operations

getFirmDebtInfo

Get firm debt information.

const debtInfo = await client.getFirmDebtInfo();

getVPosTransactionList

Get virtual POS transaction list.

const vposTransactions = await client.getVPosTransactionList({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

getFirmManagerList / addFirmManager / deleteFirmManager

Manage firm managers.

// Get list
const managers = await client.getFirmManagerList();

// Add manager
await client.addFirmManager({
  /* params */
});

// Delete manager
await client.deleteFirmManager({
  /* params */
});

Type Definitions

Enums

// Payment status types
enum PaymentStatusType {
  Waiting = 1,
  Approved = 2,
  Rejected = 3,
  Cancelled = 4,
}

// Entity status
enum EnumStatus {
  Active = 'Active',
  Passive = 'Passive',
}

// Account type
enum AccountType {
  Current = 1,
  Savings = 2,
}

// Gender
enum Gender {
  Male = 1,
  Female = 2,
}

Common Interfaces

See the full type definitions for all available interfaces.

Error Handling

The client automatically handles SOAP faults and HTTP errors.

try {
  const payments = await client.getBankPaymentList({
    paymentStatusTypeID: PaymentStatusType.Waiting,
    startDate: new Date('2024-01-01'),
    endDate: new Date('2024-01-31'),
  });
} catch (error) {
  if (error instanceof Error) {
    if (error.message.includes('SOAP Fault')) {
      console.error('SOAP Error:', error.message);
    } else if (error.message.includes('HTTP Error')) {
      console.error('Network Error:', error.message);
    } else {
      console.error('Unknown Error:', error.message);
    }
  }
}

Available Scripts

Development

pnpm run dev              # Watch mode
pnpm run build:watch      # Build in watch mode

Testing

pnpm run test             # Run tests
pnpm run test:watch       # Run tests in watch mode
pnpm run test:coverage    # Run tests with coverage
pnpm run test:light       # Light test mode
pnpm run test:serial      # Run tests serially
pnpm run test:bail        # Stop on first error

Code Quality

pnpm run lint             # Run ESLint
pnpm run lint:fix         # Fix ESLint issues
pnpm run format           # Format code with Prettier
pnpm run format:check     # Check formatting
pnpm run fix              # Fix lint and format issues

Utilities

pnpm run clean            # Clean build artifacts

Development

This project uses pnpm for package management.

Prerequisites

• Node.js 20 or higher
• pnpm 10.23.0 or higher

Install pnpm globally if you haven't already:

npm install -g pnpm

Install Dependencies

pnpm install

Build the Project

pnpm run build

Development Setup

1. Install dependencies: pnpm install
2. Run tests: pnpm test
3. Start development mode: pnpm run dev

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This is an unofficial SDK for BulutTahsilat Bank Payment Web Service. Please refer to the official BulutTahsilat documentation for the most up-to-date API information.

Credits

This SDK is built based on the official BulutTahsilat Bank Payment Web Service available at https://ws.buluttahsilat.com/WebService/WSBankPaymentService.asmx.

Support

If you encounter any issues or have questions, please open an issue on GitHub.