# go-vchasno-kassa

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

## Установка

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

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

```go
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/`.

```bash
cd examples
go run main.go
```

## Валидация

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

```go
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)
}
```

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

```go
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 использует копейки для точных денежных расчетов:

```go
// Создание суммы в копейках
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` - проверка соединения

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

```go
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