169 lines
5.0 KiB
Markdown
169 lines
5.0 KiB
Markdown
# 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 |