initial commit

2025-09-30 14:39:08 +03:00
parent 85292a94ba
commit 830b63e701
7 changed files with 472 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,169 @@
 # 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