Как из R-Keeper получать регулярную сводку по продажам заведения

В этой статье мы покажем простое решение, которое поможет отслеживать финансовые показатели своего заведения, работающего на R-Keeper. Материал даст представление о том, как может выглядеть серверная интеграция с внешними сервисами, и, надеемся, натолкнёт на новые мысли.

В решении мы используем JSON-server для эмуляции (моков) реального API R-Keeper, чтобы показать архитектуру приложения. Для существующего проекта потребуется подключение к официальному API R-Keeper с учётом авторизации и других особенностей. Кроме того, мы будем отправлять SMS через API-платформу МТС Exolve, используя переменные окружения и ключи API.

Создание эндпоинта на получение всех клиентов

Будем использовать Nest.js, который из коробки предоставляет модульную архитектуру с поддержкой TypeScript, а также JSON-server для быстрого развёртывания мокового API. Моковые данные будут имитировать работу реального API R-Keeper: их структуру мы взяли из документации R-Keeper — запроса на поиск заказов.

Установка зависимостей

Разворачиваем nest.js и устанавливаем все необходимые зависимости:

npm I -g @nestjs/cli
nest new r-keeper
npm install json-server 

Файл с моковыми данными

Создаём файл src/mock-data/clients.mock.ts и добавляем туда код:

// src/mock-data/clients.mock.ts
export const clients = [
    {
        name: 'Сергей Иванов',
        age: 34,
        phone: '[phone]',
        email: '[e-mail]',
        order: ['Пицца Маргарита', 'Мороженое', 'Чай'],
        amountPaid: 850,
        paymentDate: '2023-12-01T13:45:00',
    },
    {
        name: 'Мария Петрова',
        age: 28,
        phone: '[phone]',
        email: '[e-mail]',
        order: ['Салат Цезарь', 'Кофе'],
        amountPaid: 540,
        paymentDate: '2023-12-01T16:20:00',
    },
    {
        name: 'Александр Смирнов',
        age: 45,
        phone: '[phone]',
        email: '[e-mail]',
        order: ['Стейк', 'Картофель фри', 'Пиво'],
        amountPaid: 1300,
        paymentDate: '2023-12-01T18:30:00',
    },
    {
        name: 'Ольга Кузнецова',
        age: 22,
        phone: '[phone]',
        email: '[e-mail]',
        order: ['Паста Карбонара', 'Сок'],
        amountPaid: 670,
        paymentDate: '2023-12-01T12:15:00',
    },
    {
        name: 'Дмитрий Васильев',
        age: 30,
        phone: '[phone]',
        email: '[e-mail]',
        order: ['Бургер', 'Кола'],
        amountPaid: 500,
        paymentDate: '2023-12-01T19:00:00',
    },
]

Создание сервиса для клиентов

Создаём сервис, который будет использовать эти моковые данные. Сервисы в Nest.js отвечают за бизнес-логику и могут легко взаимодействовать с контроллерами.

nest generate service clients

Импортируем в него моковые данные и предоставляем методы для их получения:

// src/clients/clients.service.ts
import { Injectable } from '@nestjs/common'
import { clients } from '../mock-data/clients.mock'


@Injectable()
export class ClientsService {
    private clients = clients


    getAllClients() {
        return this.clients
    }
}

Создание контроллера для клиентов

Создаём контроллер, который будет обращаться к сервису для получения моковых данных:

nest generate controller clients

// src/clients/clients.controller.ts
import { Controller, Get } from '@nestjs/common'
import { ClientsService } from './clients.service'


@Controller('clients')
export class ClientsController {
    constructor(private clientsService: ClientsService) {}


    @Get()
    getAllClients() {
        return this.clientsService.getAllClients()
    }
}

Создание модуля для клиентов

nest generate module clients

// src/clients/clients.module.ts
import { Module } from '@nestjs/common'
import { ClientsController } from './clients.controller'
import { ClientsService } from './clients.service'


@Module({
    controllers: [ClientsController],
    providers: [ClientsService],
})
export class ClientsModule {}

Интеграция с основным приложением

Необходимо импортировать ClientsModule в наш основной модуль приложения (обычно это AppModule), чтобы Nest.js знал о его существовании и мог корректно управлять его жизненным циклом и зависимостями.

// src/app.module.ts
import { Module } from '@nestjs/common'
import { ClientsModule } from './clients/clients.module'


@Module({
    imports: [ClientsModule],
    controllers: [],
    providers: [],
})
export class AppModule {}

Запуск и тестирование

Запускаем приложение:

npm run start

Теперь можно тестировать API с моковыми данными, используя такие инструменты, как Postman или Curl:

curl http://localhost:3000/api/clients

Этот запрос покажет всех клиентов.

Создание эндпоинта на получение общей выручки за день

Для подсчёта всей выручки за день можно воспользоваться встроенными методами в JSON-server.

Шаг 1. Обновляем сервис

Первым делом обновим сервис, чтобы добавить метод, который будет считать выручку за конкретный день.

// src/clients/clients.service.ts
import { Injectable } from '@nestjs/common'
import { clients } from '../mock-data/clients.mock'


@Injectable()
export class ClientsService {
    private clients = clients


    getRevenueByDate(date: string) {
        return this.clients
            .filter((client) => client.paymentDate.split('T')[0] === date) // Разделяем дату и время и сравниваем только дату
            .reduce((total, client) => total + client.amountPaid, 0)
    }
}

Шаг 2. Обновляем контроллер

Добавим новый маршрут в наш контроллер, который будет использовать метод сервиса для получения выручки за определённый день.

// src/clients/clients.controller.ts
import { Controller, Get, Param } from '@nestjs/common'
import { ClientsService } from './clients.service'


@Controller('clients')
export class ClientsController {
    constructor(private clientsService: ClientsService) {}


    @Get('revenue/:date')
    getRevenueByDate(@Param('date') date: string) {
        return {
            date: date,
            totalRevenue: this.clientsService.getRevenueByDate(date),
        }
    }
}

Шаг 3. Тестирование

Теперь можно тестировать наш эндпоинт — отправлять к нему HTTP-запросы, запустив приложение. Например:

GET http://localhost:3000/clients/revenue/2023-12-01

Подключаем отправку SMS

Предположим, менеджер ресторана хочет получать информацию о закрытии смены с суммой выручки в конце рабочего дня. Для этого запрограммируем отправку этих данных по SMS. Теперь дополним код, чтобы при запросе суммы выручки он присылал сообщение через SMS API по нужному нам номеру.

Помимо интеграции МТС Exolve, понадобится создать эндпоинт и настроить аутентификацию для доступа к API Exolve.

Шаг 1. Получение доступа к API Exolve

Регистрируемся в МТС Exolve, подтверждаем свой номер, арендуем на приветственный бонус виртуальный номер и создаём там приложение. Далее получаем ключ API для аутентификации наших запросов.

Шаг 2. Установка необходимых пакетов

Для выполнения HTTP-запросов к Exolve API установим пакет axios:

npm install axios

Шаг 3. Настройка переменных окружения

Для безопасного хранения учётных данных, таких как API-ключи и номера телефонов, используем переменные окружения. Создаём файл .env в корне нашего проекта и добавляем в него следующие переменные:

EXOLVE_API_KEY=”ВАШ API КЛЮЧ EXOLVE”
EXOLVE_PHONE_NUMBER=”ВАШ НОМЕР ТЕЛЕФОНА EXOLVE”
EXOLVE_PHONE_DESTINATION=”НОМЕР ПОЛУЧАТЕЛЯ СООБЩЕНИЯ”

Значения для этих переменных берём из созданного приложения в МТС Exolve.

Необходимо добавить dotenv для загрузки этих переменных в наше приложение:

npm install dotenv

И добавляем его инициализацию в начало нашего главного файла main.ts:

import * as dotenv from 'dotenv'
dotenv.config()

Шаг 4. Расширение сервиса для отправки SMS

Добавим новый метод sendRevenueSMS в наш сервис. Он будет использовать готовую функцию для подсчёта общей суммы выручки и отправлять SMS. Обновляем файл сервиса clients:

// src/clients/clients.service.ts
import { Injectable } from '@nestjs/common'
import { clients } from '../mock-data/clients.mock'
import axios from 'axios'


@Injectable()
export class ClientsService {
    private clients = clients
    private exolveUrl = 'https://api.exolve.ru/messaging/v1/SendSMS'


    getRevenueByDate(date: string) {
        return this.clients
            .filter((client) => client.paymentDate.split('T')[0] === date)
            .reduce((total, client) => total + client.amountPaid, 0)
    }


    async sendRevenueSMS(date: string) {
        const totalRevenue = this.getRevenueByDate(date)
        const message = `Общая выручка за ${date} составила ${totalRevenue} руб.`
        try {
            const response = await axios.post(
                this.exolveUrl,
                {
                    number: process.env.EXOLVE_PHONE_NUMBER,
                    destination: process.env.EXOLVE_PHONE_DESTINATION,
                    text: message,
                },
                {
                    headers: {
                        Authorization: `Bearer ${process.env.EXOLVE_API_KEY}`,
                    },
                }
            )
            return response.data
        } catch (error) {
            console.error('Ошибка отправки SMS:', error)
            throw error
        }
    }
}

Шаг 5. Обновления контроллера

Добавим новый эндпоинт в контроллер clients. Обновляем файл clients.controller.ts следующим образом:

// src/clients/clients.controller.ts
import {
    Controller,
    Get,
    Param,
    Post,
    HttpException,
    HttpStatus,
} from '@nestjs/common'
import { ClientsService } from './clients.service'


@Controller('clients')
export class ClientsController {
    constructor(private clientsService: ClientsService) {}


    @Get('revenue/:date')
    getRevenueByDate(@Param('date') date: string) {
        return {
            date: date,
            totalRevenue: this.clientsService.getRevenueByDate(date),
        }
    }


    @Post('send-revenue-sms/:date')
    async sendRevenueSMS(@Param('date') date: string) {
        try {
            const response = await this.clientsService.sendRevenueSMS(date)
            return {
                message: 'СМС успешно отправлено',
                data: response,
            }
        } catch (error) {
            throw new HttpException(
                {
                    status: HttpStatus.BAD_REQUEST,
                    error:
                        'Ошибка при отправке смс: ' + error.message,
                },
                HttpStatus.BAD_REQUEST
            )
        }
    }
}

Шаг 6. Тестирование

После внесения изменений проводим тестирование эндпоинтов через такие инструменты, как Postman или cURL, чтобы убедиться в их корректной работе.

Отправляем запрос по эндпоинту с указанием даты, за которую мы хотим посчитать прибыль по эндпоинту:

http://localhost:3000/clients/send-revenue-sms/2023-12-01

После этого должно прийти сообщение на указанный номер.

Заключение

Использование коммуникационных API-сервисов для отправки SMS при работе с API R-Keeper демонстрирует мощный потенциал современных платформ для создания масштабируемых, эффективных и взаимосвязанных решений. Создание сервера на базе Nest.js, который может не только запросить и обработать данные о выручке через R-Keeper, но и информировать пользователей, упрощает бизнес-процессы и позволяет быстро реагировать на изменения.

Приведённый пример демонстрирует базовую архитектуру; для продакшена потребуется расширенное тестирование, настройка безопасности и полноценная интеграция с реальным API R-Keeper. Спасибо за внимание и желаем высокой выручки!

---

Подписывайтесь на наш Хаб, следите за новыми гайдами и получайте приз

Каждый понедельник мы случайным образом выбираем победителей среди новых подписчиков нашего Хабр-канала и дарим крутые призы от МТС Exolve: стильные рюкзаки, лонгсливы и мощные беспроводные зарядки. Победители прошлых розыгрышей и правила.