# go-vchasno-kassa

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

## Установка

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```go
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. Изменение дефолтов в процессе работы

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

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

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

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

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

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

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

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

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

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

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

```go
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 методы

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

```go
client.QuickSell(ctx, 100.00)

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

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

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

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