go-vchasno-kassa

Go SDK для работы с API кассы ВЧАСНО - украинской системы фискализации.

Установка

go get gitea.jeezft.xyz/jeezft/go-vchasno-kassa

Быстрый старт

Базовое использование

package main

import (
    "context"
    "log"
    
    "gitea.jeezft.xyz/jeezft/go-vchasno-kassa"
)

func main() {
    client := vchasno.NewClient(vchasno.Config{
        Token: "your-api-token-here",
    })
    
    ctx := context.Background()
    
    response, err := client.QuickSell(ctx, 100.00)
    if err != nil {
        log.Fatal(err)
    }
    
    log.Printf("Sale created: %s", response.Info.Doccode)
}

С дефолтными параметрами

client := vchasno.NewClient(vchasno.Config{
    Token:   "your-api-token-here",
    Cashier: "Иванов",
    Source:  "parking",
    Defaults: &vchasno.DefaultParams{
        ProductName:    "Парковка",
        Comment:        "Оплата парковки",
        Taxgrp:         "1",
        PayType:        vchasno.PayTypeCash,
        DefaultTimeout: 30 * time.Second,
    },
})

response, _ := client.QuickSell(ctx, 50.00)

С Builder Pattern

response, err := client.NewSellParams().
    Name("Парковка VIP").
    Price(150.00).
    Cnt(2).
    Comment("2 часа").
    PayCash().
    ExecuteDefault()

Функциональность

Работа со сменами

• Открытие смены (OpenShift)
• Закрытие смены с Z-отчетом (CloseShift)

Продажи

• Создание чеков с оплатой наличными
• Создание чеков с оплатой картой
• Поддержка дополнительных данных клиента
• Автоматический расчет сумм

Z-отчет содержит

• Количество чеков (продажа/возврат)
• Сводку по налогам
• Информацию о платежах
• Остатки в кассе
• Детальную информацию по налоговым группам

Структура проекта

api/
├── client.go      - Клиент API
├── constants.go   - Константы (типы задач, платежей)
├── requests.go    - Структуры запросов
├── responses.go   - Структуры ответов
├── helpers.go     - Вспомогательные функции
└── fiscal.go      - Методы API

Примеры использования

1. Быстрая продажа (QuickSell)

response, err := client.QuickSell(ctx, 100.00)

Использует все дефолтные параметры из конфигурации.

2. Быстрая продажа с названием

response, err := client.QuickSellNamed(ctx, "Парковка VIP", 150.00)

3. Builder Pattern - базовый пример

response, err := client.NewSellParams().
    Price(100.00).
    ExecuteDefault()

4. Builder Pattern - полный пример

response, err := client.NewSellParams().
    Name("Парковка premium").
    Price(200.00).
    Cnt(2).
    Disc(20.00).
    Comment("Скидка 10%").
    Taxgrp("1").
    PayCash().
    ExecuteDefault()

5. Оплата картой через Builder

response, err := client.NewSellParams().
    Name("Услуга парковки").
    Price(150.00).
    PayCard("411111****1111", "305299", "123456789012", "123456").
    Userinfo("user@example.com", "+380501234567").
    ExecuteDefault()

6. Традиционный способ (без Builder)

response, err := client.Sell(ctx, vchasno.SellParams{
    Name:    "Товар",
    Cnt:     2,
    Price:   50.00,
    Taxgrp:  "1",
    PayType: vchasno.PayTypeCash,
})

7. Полный рабочий цикл

client := vchasno.NewClient(vchasno.Config{
    Token: "your-token",
    Defaults: &vchasno.DefaultParams{
        ProductName: "Парковка",
        Taxgrp:      "1",
    },
})

ctx := context.Background()

client.OpenShift(ctx)

client.NewSellParams().Price(50.00).PayCash().ExecuteDefault()
client.NewSellParams().Price(100.00).PayCash().ExecuteDefault()
client.NewSellParams().Price(75.00).PayCard("411111****1111", "305299", "123456789012", "123456").ExecuteDefault()

zReport, _ := client.CloseShift(ctx)
fmt.Printf("Итого за смену: %.2f\n", zReport.Info.Safe)

8. Изменение дефолтов в процессе работы

client.SetDefaults(vchasno.DefaultParams{
    ProductName:    "VIP Парковка",
    Comment:        "VIP зона",
    Taxgrp:         "2",
    PayType:        vchasno.PayTypeCard,
    DefaultTimeout: 60 * time.Second,
})

response, _ := client.QuickSell(ctx, 200.00)

9. Множественные продажи

prices := []float64{50.00, 75.00, 100.00, 125.00}

for _, price := range prices {
    client.NewSellParams().
        Price(price).
        PayCash().
        ExecuteDefault()
}

10. Собственный таймаут

response, err := client.NewSellParams().
    Price(100.00).
    ExecuteWithTimeout(45 * time.Second)

Хелперы и удобные функции

DefaultParams - дефолтные параметры

При создании клиента можно задать дефолтные значения, которые будут использоваться автоматически:

client := vchasno.NewClient(vchasno.Config{
    Token: "your-token",
    Defaults: &vchasno.DefaultParams{
        ProductName:    "Парковка",        
        Comment:        "Оплата услуг",    
        Taxgrp:         "1",               
        PayType:        vchasno.PayTypeCash,   
        DefaultTimeout: 30 * time.Second,  
    },
})

Builder Pattern

Builder Pattern позволяет строить параметры продажи в цепочке вызовов:

client.NewSellParams().
    Name("Товар").
    Price(100.00).
    Cnt(2).
    Disc(10.00).
    Comment("Комментарий").
    Taxgrp("1").
    PayCash().
    ExecuteDefault()

Доступные методы Builder:

• Name(string) - название товара
• Price(float64) - цена
• Cnt(int) - количество
• Disc(float64) - скидка
• Comment(string) - комментарий
• Taxgrp(string) - налоговая группа
• PayCash() - оплата наличными
• PayCard(cardmask, bankID, rrnCode, authCode) - оплата картой
• Userinfo(email, phone) - данные клиента
• Build() - получить SellParams
• Execute(ctx) - выполнить с контекстом
• ExecuteWithTimeout(duration) - выполнить с таймаутом
• ExecuteDefault() - выполнить с дефолтным таймаутом

QuickSell методы

Для быстрых продаж:

client.QuickSell(ctx, 100.00)

client.QuickSellNamed(ctx, "Парковка", 100.00)

Изменение дефолтов

Дефолтные параметры можно изменить в любой момент:

client.SetDefaults(vchasno.DefaultParams{
    ProductName: "Новое название",
    PayType:     vchasno.PayTypeCard,
})

defaults := client.GetDefaults()

Константы

Типы задач

• vchasno.TaskOpenShift = 0 - Открытие смены (также доступен как api.TaskOpenShift)
• vchasno.TaskSell = 1 - Продажа (также доступен как api.TaskSell)
• vchasno.TaskZReport = 11 - Z-отчет (также доступен как api.TaskZReport)

Типы платежей

• vchasno.PayTypeCash = 0 - Оплата наличными (также доступен как api.PayTypeCash)
• vchasno.PayTypeCard = 2 - Оплата картой (также доступен как api.PayTypeCard)

Все константы экспортируются как из основного пакета vchasno, так и из подпакета api для удобства использования.

Структуры ответов

SellResponse

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

ZReportResponse

Используется для закрытия смены. Содержит детальную информацию:

• Receipt - статистика по чекам
• Summary - итоговые суммы
• Taxes - разбивка по налогам
• Pays - способы оплаты
• Money - движение наличных
• Cash - остатки по безналичным

API Reference

Полная документация API ВЧАСНО: https://documenter.getpostman.com/view/26351974/2s93shy9To