324 lines
9.0 KiB
Markdown
324 lines
9.0 KiB
Markdown
# 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 |