t-kassa-api

Библиотека для взаимодействия с API Т-Кассы.

import { TKassa } from "t-kassa-api";

const ткасса = new TKassa(process.env.TERMINAL_KEY, process.env.PASSWORD, {
    server: "https://rest-api-test.tinkoff.ru",
});

const result = await ткасса.init({
    Amount: 1000,
    OrderId: "12",
});

console.log(result);

API Reference

Фичи

• Генерируется исходя из OpenAPI спецификации
• Очень удобная работа с нотификацией (webhook) с умными фильтрами
• Имеет в себе webhook адаптеры для самых популярных фреймворков
• Удобна и для нескольких касс
• Отличная документация кода с помощью JSDoc (сгенерировано из OpenAPI)
• Современная и с умнейшими типами
• 0 зависимостей
• Берёт работу с подписью запроса на себя
• Есть на JSR

Webhook

Пример использования webhook с фреймворком Hono

import { Hono } from "hono";
import { TKassa, webhookHandler, filters } from "t-kassa-api";

const ткасса = new TKassa(process.env.TERMINAL_KEY, process.env.PASSWORD);

ткасса.on(
    filters.and(
        filters.equal("Status", "SUCCESS"),
        filters.notNullable("RebillId")
    ),
    (context) => {
        // при этом типы понимают фильтры
    }
);

const app = new Hono();

app.get("/", webhookHandler("hono"));

Поддерживаемые webhook адаптеры

• Elysia
• Fastify
• Hono
• Express
• Koa
• node:http
• Bun.serve
• std/http (Deno.serve)

или любой другой фреймворк

// a non-existing framework for the example
import { App } from "some-http-framework";
import { TKassa } from "t-kassa-api";

const ткасса = new TKassa(process.env.TERMINAL_KEY, process.env.PASSWORD, {
    server: "https://rest-api-test.tinkoff.ru",
});

const app = new App().post("/t-kassa", async (req) => {
    // req.body must be json equivalent to Webhook notification body
    await ткасса.emit(req.body);
});

app.listen(80);

Режим мульти-кассы

Не всегда бывает удобным передача параметров одной кассы в конструктор класса, поэтому и появился режим мульти-кассы. Он позволяет вам не указывать TerminalKey и Password.

import { TKassa } from "t-kassa-api";

const ткасса = new TKassa();

const result = await ткасса.init({
    Amount: 1000,
    OrderId: "12",
    TerminalKey: "12312sf",
    Password: "123123231",
});

console.log(result);

И как вы можете заметить, теперь требуется указывать TerminalKey и Password в теле запроса. И в типах это тоже выражено! Магия? Не иначе.

Но как тогда получать webhook события? (нотификацию)

Для этого вам понадобится указать функцию первым аргументом конструктора.

import { TKassa } from "t-kassa-api";

const ткасса = new TKassa((body) => {
    const [kassa] = await db
        .select()
        .from(kassaTable)
        .where(eq(kassaTable.terminalKey, body.TerminalKey));

    if (!kassa) throw new Error("Касса не найдена");

    return {
        Password: kassa.password,
        custom: { kassa },
    };
});

ткасса.on(
    filters.and(
        filters.equal("Status", "SUCCESS"),
        filters.notNullable("RebillId")
    ),
    (context, { kassa }) => {
        // и тут появляется вторым аргументов переданное вами значение в custom
    }
);

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

TODO:

• поддержать application/x-www-form-urlencoded