Skip to content
This repository has been archived by the owner on Jul 16, 2024. It is now read-only.

Latest commit

 

History

History
278 lines (209 loc) · 14 KB

README.ru.md

File metadata and controls

278 lines (209 loc) · 14 KB
Raw

QIWI SDK

Типизированный SDK для API QIWI Кошелька для NodeJS

QIWI SDK

Test Status Downloads last commit codecov GitHub qiwi-sdk Known Vulnerabilities Quality npm license MIT Size Codacy Badge

Язык: Русский | English

🍬 Почему именно эта библиотека?

  1. Полная. Покрывает следующие API:
  2. Простая. Все методы названы как в документации QIWI и собраны в подклассы. Ко всем методам есть комментарии JSDoc.
  3. Надёжная. Библиотека написана на TypeScript и покрыта тестами.
  4. Безопасная. У библиотеки всего 1 зависимость (axios), и она постоянно сканируется Code QL и Snyk на наличие уязвимостей.
  5. Совместимая. Код с версии 1.1.0 (18 янв. 2020) будет работать на версии 3.1.0 (26 апр. 2022) с незначительными изменениями. Так-же qiwi-sdk предоставляет классы совместимости для упрощения миграции с похожих библиотек.
  6. Мощная. Поддерживается работа с прокси, и даже редко используемые API:
    • Персональные WebHook'и;
    • Блокировка метода оплаты P2P;
    • API работы с картами Qiwi Master.
    • Интеграция с Express из коробки
  7. Кроссплатформенная. Поддерживает работу в браузере

Язык: Русский | English

📦 Установка

  • Используя npm 
    npm i qiwi-sdk
  • Используя Yarn 
    yarn add qiwi-sdk
  • Используя pnpm 
    pnpm add qiwi-sdk

Язык: Русский | English

🛠️ Использование

Импорт

Из библиотеки можно импортировать все API по отдельности, так как случаи их применения разные.

  • CommonJS (способ по умолчанию для Node JS) 
    const { P2p, Wallet, Detector } = require("qiwi-sdk");
  • TypeScript или ES Модули 
    import { P2p, Wallet, Detector } from "qiwi-sdk";

Документация

👉 Смотреть документацию API 👈

В таблице указанны текущие реализованные API.

Класс (Legacy v2) - это класс совместимости только для тех, кто переходит с версии 2. Остальным рекомендуется использовать новый вариант работы с API - Класс v3.

Класс (v3) Класс (Legacy v2) Документация от QIWI Рекомендованное название переменной
Wallet Personal https://developer.qiwi.com/ru/qiwi-wallet-personal wallet (или qiwi)
P2p P2P https://developer.qiwi.com/ru/p2p-payments p2p
P2p - https://developer.qiwi.com/ru/bill-payments p2p (или payments)
Detector DetectorCompat https://developer.qiwi.com/ru/qiwi-wallet-personal/#search-providers detector

Чтобы посмотреть детальную документацию по классу, нажмите на его название.

Миграция

  1. Миграция с версии 2 на 3;
  2. Миграция с версии 1 на 2 (на всякий случай);
  3. Миграция c node-qiwi;
  4. Миграция с @qiwi/bill-payments-node-js-sdk.

Создание

const { Wallet, P2p, Detector } = require("qiwi-sdk");

// ✅ - Правильный способ (с версии 3.0.0)
const wallet = Wallet.create(process.env.QIWI_TOKEN, process.env.QIWI_WALLET);
const p2p = P2p.create(process.env.QIWI_SECRET_KEY, process.env.QIWI_PUBLIC_KEY);
const detect = Detector.create();

// ✅ - Тоже правильный способ (с версии 3.2.0)
const wallet = new Wallet({
  token: process.env.QIWI_TOKEN,
  walletId: process.env.QIWI_WALLET
});
const p2p = new P2p({
  secretKey: process.env.QIWI_SECRET_KEY,
  publicKey: process.env.QIWI_PUBLIC_KEY
});
const detect = new Detector();

Переменные окружения

В этом примере использовались следующие переменные окружения. Все данные для доступа к API рекомендуется хранить в переменных окружения либо в другом защищённом месте, но не в коде.

Название Тип Описание
QIWI_TOKEN Строка(32 сим) - Hex Токен киви, полученный на https://qiwi.com/api
QIWI_WALLET Строка(10-16 сим) - только цифры Номер телефона кошелька, к которому привязан
QIWI_SECRET_KEY и QIWI_PUBLIC_KEY Строки Пара ключей, созданные на https://qiwi.com/p2p-admin/transfers/api

Примеры

Получение информации о кошельке

const wallet = Wallet.create(process.env.QIWI_TOKEN);

wallet.personProfile.getCurrent().then(console.log);
// => { contractInfo: {...}, authInfo: {...}, userInfo: {...} }

Отправка платежа

const wallet = Wallet.create(process.env.QIWI_TOKEN);

// 100 руб. с рублёвого счёта на QIWI (99) `79123456789` включая комиссию
// Всё вышеописанное настраивается
wallet.payments.quickPay({
  amount: 100,
  account: "79123456789"
});

Выставление счёта

const p2p = P2p.create(process.env.QIWI_SECRET_KEY);

p2p.bills
  .create({
    amount: {
      value: 1000,
      currency: P2p.Currency.RUB
    },
    successUrl: "https://youtu.be/dQw4w9WgXcQ"
  })
  .then(console.log);

// => { payUrl: 'https://oplata.qiwi.com/...' }

Использование прокси

const { SocksProxyAgent } = require("socks-proxy-agent");

const wallet = Wallet.create(process.env.QIWI_TOKEN);
wallet.agent = new SocksProxyAgent("socks://login:password@host:port");

// Тут делаем что то с кошельком

// Не забываем очистить объект от агента
wallet.agent = undefined;

Интеграция с Express

const p2p = P2p.create(process.env.QIWI_SECRET_KEY);
const app = express();

app.post(
  "/webhook/qiwi",
  p2p.notificationMiddleware({}, (req, res) => {
    // Тело запроса
    console.log(req.body);

    // { "siteId": "9hh4jb-00", "billId": "cc961e8d-d4d6-4f02-b737-2297e51fb48e", ... }
  })
);

app.use((error, req, res, next) => {
  if (error instanceof P2pBillNotificationError) {
    // Кто то отправил невалидное уведомление
    console.log(error);
  }

  return next();
});

Полные примеры

  1. 🥝 Получение информации о кошельке
  2. 📬 Отправка платежа куда угодно
  3. 🛠️ Создание ключей P2P и создание счёта
  4. 🔐 Получение лимитов (на ESM)
  5. 🤖 Телеграм бот с оплатой напрямую (по номеру кошелька)
  6. 🖥️ Магазин на Express
  7. 🌐 Использование прокси

Язык: Русский | English

🎩 О пакете

Лицензия

Проект распространяется под лицензией MIT. Смотрите LICENSE.txt

FOSSA Status

Цели проекта

  • Покрыть все API QIWI (в том числе для юридических лиц)
    • API QIWI Кошелька - (все API)
    • Прием платежей
    • Денежные выплаты
  • Сохранять обратную совместимость
    • v2 и v3
    • v1 и v2
  • Обеспечить максимальную надёжность и качество кода
    • Типы: TypeScript
    • Тесты: Jest, Codecov
    • Авто-тесты в репозитории: Github Actions
    • Статический анализ: Eslint, Prettier, Editorconfig
    • Безопасность: Eslint Плагин, Code QL, ручная проверка в Snyk

Содействие (Contributing)

  1. ⁉️ Не стесняйтесь писать Issues
  2. 🛠️ Если хотите что-то поправить в коде, следуйте CONTRIBUTING.md
  3. 💸 Так-же можете отправить донат 👉 https://qiwi.com/n/ALEXXGRIB
  4. 🌟 Или поставить библиотеке звёздочку, если она вам понравилась

Поддержка

Вы можете написать Issue, а если я долго не отвечаю пишите в

Telegram: @AlexXanderGrib

💜 Пакет для YooMoney

Интересует приём платежей от физ. лиц по РФ?

Попробуйте мою другую библиотеку - SDK для ЮMoney 👉 github.com/AlexXanderGrib/yoomoney-sdk

Язык: Русский | English