npm package: @qrexpress/sbp-c2b
Description: Библиотека для интеграции с Системой Быстрых Платежей (СБП) через динамические QR-коды
Author: qrexpress
Latest version: 1.0.2

# SbpC2BLib

**SbpC2BLib** — это библиотека для интеграции с Системой Быстрых Платежей (СБП) от **ТРР «Золотая корона»** с использованием динамических QR-кодов. Она предоставляет API для создания платежей, отслеживания их статуса и обработки событий

## Основные возможности

- Генерация платежей с использованием динамических QR-кодов.
- Поддержка событий для обработки ключевых этапов платежа (создание, завершение, ошибка).
- Опрос статуса платежа с использованием встроенного polling механизма.

## Установка

Установите библиотеку через npm или yarn:

```bash
npm install @qrexpress/sbp-c2b
```
или
```bash
yarn add @qrexpress/sbp-c2b
```

## Использование

### Инициализация библиотеки

```javascript
import SbpC2BLib from '@qrexpress/sbp-c2b';

const sbpC2b = new SbpC2BLib({
    token: 'YOUR_TOKEN', // Секретный токен для авторизации
    entityId: 'YOUR_ENTITY_ID', // ID Юр.Лица
    merchantId: 'YOUR_MERCHANT_ID', // ID ТСП
    account: 'YOUR_ACCOUNT', // Счет для платежа
    options: {
        qrSize: 400, // Размер QR-кода (по умолчанию 400)
        requestLimit: 25, // Лимит запросов (по умолчанию 25)
        pollingInterval: 2500 // Период между запросами статуса платежа (по умолчанию 2500 ms)
    }
});
```

### Создание платежа

```javascript
const payment = await sbpC2b.createPayment(10000, 'Оплата за услуги');
console.log('Платеж создан:', payment);
```

### Опрос статуса платежа

```javascript
sbpC2b.startPaymentPolling(payment);

// Подписка на события
sbpC2b.on('qrcGenerate', (data) => {
    console.log('Статус создания платежа:', data);
});

sbpC2b.on('qrcPollingStep', (data) => {
    console.log('Шаг опроса:', data);
});

sbpC2b.on('qrcFinal', (data) => {
    console.log('Финальный статус:', data);
});

sbpC2b.on('error', (error) => {
    console.error('Ошибка:', error);
});
```

### Остановка опроса

```javascript
sbpC2b.stopPaymentPolling('Опрос остановлен вручную');
```

## Параметры конструктора

| Параметр       | Тип       | Описание                                     | Обязательный |
|----------------|-----------|---------------------------------------------|--------------|
| `token`        | `string`  | Секретный токен для авторизации            | Да           |
| `entityId`     | `string`  | ID Юр.Лица                                | Да           |
| `merchantId`   | `string`  | ID ТСП                                | Да           |
| `account`      | `string`  | Счет для платежа                           | Да           |
| `options.qrSize`        | `number`  | Размер QR-кода (в пикселях).                | Нет          |
| `options.requestLimit`  | `number`  | Максимальное количество запросов.          | Нет          |

## Методы

### `createPayment(amount: number, paymentPurpose?: string): Promise<PaymentData>`
Создает новый платеж.
- **amount**: Стоимость платежа (в копейках).
- **paymentPurpose**: Описание платежа (опционально).
- **Возвращает**: Объект `PaymentData` с информацией о платеже.

### `startPaymentPolling(payment: PaymentData): void`
Запускает опрос статуса платежа.
- **payment**: Объект `PaymentData`.

### `stopPaymentPolling(reason?: string): void`
Останавливает опрос статуса платежа.
- **reason**: Причина остановки (опционально).

### `on(event: string, callback: Function): void`
Подписывается на событие.
- **event**: Название события (`qrcGenerate`, `qrcPollingStep`, `qrcFinal`, `error`).
- **callback**: Функция-обработчик.

### `off(event: string, callback: Function): void`
Отписывается от события.
- **event**: Название события (`qrcGenerate`, `qrcPollingStep`, `qrcFinal`, `error`).
- **callback**: Функция-обработчик.

## События

- **qrcGenerate**: Вызывается после генерации QR-кода.
- **qrcPollingStart**: Вызывается при начале опроса статуса платежа
- **qrcPollingStep**: Вызывается на каждом шаге опроса статуса платежа.
- **qrcPollingEnd**: Вызывается при завершении опроса статуса платежа.
- **qrcFinal**: Вызывается, когда платеж завершен.
- **error**: Вызывается при возникновении ошибки.

## Пример

```javascript
import SbpC2BLib from '@qrexpress/sbp-c2b';

const sbpC2b = new SbpC2BLib({
    token: 'YOUR_TOKEN',
    entityId: 'YOUR_ENTITY_ID',
    merchantId: 'YOUR_MERCHANT_ID',
    account: 'YOUR_ACCOUNT'
});

sbpC2b.on('qrcPollingStep', (data) => {
    console.log('Опрос статуса:', data);
});

sbpC2b.on('qrcFinal', (data) => {
    console.log('Платеж завершен:', data);
});

try {
    const payment = await sbpC2b.createPayment(15000, 'Оплата товара');
    console.log('Платеж создан:', payment);

    sbpC2b.startPaymentPolling(payment);
} catch (error) {
    console.error('Ошибка:', error);
}
```

## Лицензия

Проект распространяется под лицензией MIT. Подробности см. в файле LICENSE.