complete structure revamp
This commit is contained in:
371
README.md
371
README.md
@@ -5,165 +5,318 @@ Go SDK для работы с API кассы ВЧАСНО - украинской
|
||||
## Установка
|
||||
|
||||
```bash
|
||||
go get git.jeezft.xyz/rk/go-vchasno-kassa
|
||||
go get gitea.jeezft.xyz/jeezft/go-vchasno-kassa
|
||||
```
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
### Базовое использование
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"log"
|
||||
"time"
|
||||
|
||||
"git.jeezft.xyz/rk/go-vchasno-kassa"
|
||||
"gitea.jeezft.xyz/jeezft/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)
|
||||
response, err := client.QuickSell(ctx, 100.00)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
log.Printf("Fiscal receipt created: %s", response.FiscalNumber)
|
||||
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: api.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()
|
||||
```
|
||||
|
||||
## Функциональность
|
||||
|
||||
### Работа с фискальными чеками
|
||||
- Создание фискальных чеков через единый API эндпоинт `/api/v3/fiscal/execute`
|
||||
- Получение информации о фискализованном чеке
|
||||
- Отмена фискальных чеков
|
||||
- Поддержка различных типов оплаты (наличные, карта)
|
||||
- Автоматический расчет НДС и налогов
|
||||
### Работа со сменами
|
||||
- Открытие смены (`OpenShift`)
|
||||
- Закрытие смены с Z-отчетом (`CloseShift`)
|
||||
|
||||
### Отчеты
|
||||
- X-отчет (промежуточный отчет без обнуления)
|
||||
- Z-отчет (итоговый отчет с обнулением кассы)
|
||||
### Продажи
|
||||
- Создание чеков с оплатой наличными
|
||||
- Создание чеков с оплатой картой
|
||||
- Поддержка дополнительных данных клиента
|
||||
- Автоматический расчет сумм
|
||||
|
||||
### Валидация данных
|
||||
- Проверка корректности сумм и количества
|
||||
- Валидация обязательных полей
|
||||
- Проверка соответствия общей суммы и оплат
|
||||
### Z-отчет содержит
|
||||
- Количество чеков (продажа/возврат)
|
||||
- Сводку по налогам
|
||||
- Информацию о платежах
|
||||
- Остатки в кассе
|
||||
- Детальную информацию по налоговым группам
|
||||
|
||||
## Структура проекта
|
||||
|
||||
```
|
||||
api/
|
||||
├── client.go - Клиент API
|
||||
├── constants.go - Константы (типы задач, платежей)
|
||||
├── requests.go - Структуры запросов
|
||||
├── responses.go - Структуры ответов
|
||||
├── helpers.go - Вспомогательные функции
|
||||
└── fiscal.go - Методы API
|
||||
```
|
||||
|
||||
## Примеры использования
|
||||
|
||||
Полные примеры использования находятся в папке `examples/`.
|
||||
|
||||
```bash
|
||||
cd examples
|
||||
go run main.go
|
||||
```
|
||||
|
||||
## Валидация
|
||||
|
||||
SDK включает встроенную валидацию фискальных чеков:
|
||||
### 1. Быстрая продажа (QuickSell)
|
||||
|
||||
```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)
|
||||
}
|
||||
response, err := client.QuickSell(ctx, 100.00)
|
||||
```
|
||||
|
||||
## Обработка ошибок
|
||||
Использует все дефолтные параметры из конфигурации.
|
||||
|
||||
### 2. Быстрая продажа с названием
|
||||
|
||||
```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)
|
||||
}
|
||||
}
|
||||
response, err := client.QuickSellNamed(ctx, "Парковка VIP", 150.00)
|
||||
```
|
||||
|
||||
## Работа с деньгами
|
||||
|
||||
SDK использует копейки для точных денежных расчетов:
|
||||
### 3. Builder Pattern - базовый пример
|
||||
|
||||
```go
|
||||
// Создание суммы в копейках
|
||||
price := vchasno.NewMoney(10.50) // 1050 копеек
|
||||
|
||||
// Конвертация обратно в гривны
|
||||
amount := price.ToFloat64() // 10.50
|
||||
|
||||
// Создание налога
|
||||
tax := vchasno.NewTax(4.0, vchasno.NewMoney(0.42)) // 4% НДС
|
||||
response, err := client.NewSellParams().
|
||||
Price(100.00).
|
||||
ExecuteDefault()
|
||||
```
|
||||
|
||||
## Типы операций
|
||||
|
||||
Через эндпоинт `/api/v3/fiscal/execute` выполняются следующие команды:
|
||||
|
||||
- `create_receipt` - создание фискального чека
|
||||
- `get_receipt` - получение информации о чеке
|
||||
- `cancel_receipt` - отмена чека
|
||||
- `x_report` - получение X-отчета
|
||||
- `z_report` - получение Z-отчета
|
||||
- `ping` - проверка соединения
|
||||
|
||||
## Конфигурация
|
||||
### 4. Builder Pattern - полный пример
|
||||
|
||||
```go
|
||||
client := vchasno.NewClient(vchasno.Config{
|
||||
BaseURL: "https://kasa.vchasno.ua", // необязательно, по умолчанию
|
||||
Token: "your-token", // обязательно
|
||||
Timeout: 30 * time.Second, // необязательно
|
||||
HTTPClient: &http.Client{...}, // необязательно
|
||||
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: api.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: api.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: api.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: api.PayTypeCard,
|
||||
})
|
||||
|
||||
defaults := client.GetDefaults()
|
||||
```
|
||||
|
||||
## Константы
|
||||
|
||||
### Типы задач
|
||||
- `api.TaskOpenShift = 0` - Открытие смены
|
||||
- `api.TaskSell = 1` - Продажа
|
||||
- `api.TaskZReport = 11` - Z-отчет
|
||||
|
||||
### Типы платежей
|
||||
- `api.PayTypeCash = 0` - Оплата наличными
|
||||
- `api.PayTypeCard = 2` - Оплата картой
|
||||
|
||||
## Структуры ответов
|
||||
|
||||
### SellResponse
|
||||
Используется для продаж и открытия смены. Содержит базовую информацию о документе.
|
||||
|
||||
### ZReportResponse
|
||||
Используется для закрытия смены. Содержит детальную информацию:
|
||||
- `Receipt` - статистика по чекам
|
||||
- `Summary` - итоговые суммы
|
||||
- `Taxes` - разбивка по налогам
|
||||
- `Pays` - способы оплаты
|
||||
- `Money` - движение наличных
|
||||
- `Cash` - остатки по безналичным
|
||||
|
||||
## API Reference
|
||||
|
||||
Полная документация API ВЧАСНО доступна по адресу: https://documenter.getpostman.com/view/26351974/2s93shy9To
|
||||
Полная документация API ВЧАСНО: https://documenter.getpostman.com/view/26351974/2s93shy9To
|
||||
Reference in New Issue
Block a user