go-vchasno-kassa

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

Установка

go get git.jeezft.xyz/rk/go-vchasno-kassa

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

package main

import (
    "context"
    "log"
    "time"
    
    "git.jeezft.xyz/rk/go-vchasno-kassa"
)

func main() {
    client := vchasno.NewClient(vchasno.Config{
        Token: "your-api-token-here",
        Timeout: 30 * time.Second,
    })
    
    ctx := context.Background()
    
    // Проверка подключения
    if err := client.Ping(ctx); err != nil {
        log.Fatal(err)
    }
    
    // Создание фискального чека
    receipt := vchasno.FiscalReceipt{
        Cashier:      "Иванов И.И.",
        CashierTaxID: "1234567890",
        Items: []vchasno.ReceiptItem{
            {
                Name:     "Parking on obj1",
                Code:     "PARK001",
                Price:    vchasno.NewMoney(10.00),
                Quantity: 2.0,
                Amount:   vchasno.NewMoney(20.00),
                Tax:      vchasno.NewTax(4.0, vchasno.NewMoney(0.80)),
            },
        },
        Payments: []vchasno.Payment{
            {
                Type:   "cash",
                Amount: vchasno.NewMoney(20.00),
            },
        },
        Total:    vchasno.NewMoney(20.00),
        TaxTotal: vchasno.NewMoney(0.80),
    }
    
    response, err := client.CreateFiscalReceipt(ctx, receipt)
    if err != nil {
        log.Fatal(err)
    }
    
    log.Printf("Fiscal receipt created: %s", response.FiscalNumber)
}

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

Работа с фискальными чеками

• Создание фискальных чеков через единый API эндпоинт /api/v3/fiscal/execute
• Получение информации о фискализованном чеке
• Отмена фискальных чеков
• Поддержка различных типов оплаты (наличные, карта)
• Автоматический расчет НДС и налогов

Отчеты

• X-отчет (промежуточный отчет без обнуления)
• Z-отчет (итоговый отчет с обнулением кассы)

Валидация данных

• Проверка корректности сумм и количества
• Валидация обязательных полей
• Проверка соответствия общей суммы и оплат

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

Полные примеры использования находятся в папке examples/.

cd examples
go run main.go

Валидация

SDK включает встроенную валидацию фискальных чеков:

receipt := vchasno.FiscalReceipt{
    Cashier:      "Иванов И.И.",
    CashierTaxID: "1234567890",
    Items:        []vchasno.ReceiptItem{...},
    Payments:     []vchasno.Payment{...},
    Total:        vchasno.NewMoney(100.00),
    TaxTotal:     vchasno.NewMoney(4.00),
}

if err := receipt.Validate(); err != nil {
    log.Fatal("Validation error:", err)
}

Обработка ошибок

response, err := client.CreateFiscalReceipt(ctx, receipt)
if err != nil {
    switch {
    case errors.Is(err, vchasno.ErrMissingToken):
        log.Println("Отсутствует токен авторизации")
    default:
        log.Printf("API error: %v", err)
    }
}

Работа с деньгами

SDK использует копейки для точных денежных расчетов:

// Создание суммы в копейках
price := vchasno.NewMoney(10.50) // 1050 копеек

// Конвертация обратно в гривны
amount := price.ToFloat64() // 10.50

// Создание налога
tax := vchasno.NewTax(4.0, vchasno.NewMoney(0.42)) // 4% НДС

Типы операций

Через эндпоинт /api/v3/fiscal/execute выполняются следующие команды:

• create_receipt - создание фискального чека
• get_receipt - получение информации о чеке
• cancel_receipt - отмена чека
• x_report - получение X-отчета
• z_report - получение Z-отчета
• ping - проверка соединения

Конфигурация

client := vchasno.NewClient(vchasno.Config{
    BaseURL:    "https://kasa.vchasno.ua", // необязательно, по умолчанию
    Token:      "your-token",              // обязательно
    Timeout:    30 * time.Second,          // необязательно
    HTTPClient: &http.Client{...},         // необязательно
})

API Reference

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