Refactor README files to update project status and installation instr…

…uctions
l-d-t · Sep 24, 2024 · ad11b84 · ad11b84
1 parent 796692f
commit ad11b84
Show file tree

Hide file tree

Showing 2 changed files with 248 additions and 8 deletions.
diff --git a/README-HR.md b/README-HR.md
@@ -13,7 +13,7 @@
 FiskalHR Go je Go modul dizajniran za fiskalizaciju. Cilj ovog modula je pružiti dobro održavano, učinkovito i jednostavno rješenje s ugrađenim certifikatima za provjeru potpisa, čineći je jednostavnom za korištenje.
 Temeljeno na ["Fiskalizacija" specifikaciji v2.5](https://www.porezna-uprava.hr/HR_Fiskalizacija/Documents/Fiskalizacija%20-%20Tehnicka%20specifikacija%20za%20korisnike_v2.5._23_10_23pdf.pdf)
 
-**Napomena:** Ovaj projekt je trenutno u izradi i još nije upotrebljiv.
+**Napomena:** Ovaj projekt je trenutno u tijeku i u alfa fazi te nije potpuno dovršen. Nije preporučeno za korištenje u produkciji, ali uskoro dolazi.
 
 [README in English](README.md)
 
@@ -32,11 +32,132 @@ Temeljeno na ["Fiskalizacija" specifikaciji v2.5](https://www.porezna-uprava.hr/
 
 ## Instalacija
 
-Ovaj projekt još nije dostupan za instalaciju jer je još uvijek u razvoju.
+U korijenu vašeg projekta preuzmite modul
+
+```
+go get github.com/l-d-t/fiskalhrgo
+```
 
 ## Korištenje
 
-Vodič i dokumentacija dolaze uskoro, kada prestanu promjene koje narušavaju kompatibilnost i biblioteka bude kompletna i stabilna.
+Minimalni jednostavni primjer CIS pinga koristeći EchoRequest i dohvaćanje nekih informacija o certifikatu.
+
+Pošaljite jednostavan minimalni račun, dobijte JIR.
+
+```go
+package main
+
+import (
+    "fmt"
+    "log"
+    "time"
+)
+
+func main() {
+    // Create a new FiskalEntity
+    fiskalEntity, err := NewFiskalEntity(
+        "12345678901", // OIB
+        true,          // sustavPDV
+        "Location1",   // locationID, if not DEMO MODE have to be registered
+                      // with ePorezna
+        true,          // centralized invoice numbers
+        true,          // demoMode, if true expected a valid Fiskal demo
+                      // certificate
+        true,          // chk_expired
+        "cert.p12",    // certPath
+        "password",    // certPassword
+    )
+    if err != nil {
+        log.Fatalf("Failed to create FiskalEntity: %v", err)
+    }
+
+    errPing := fiskalEntity.PingCIS()
+    if errPing != nil {
+        log.Fatalf("Failed to make Ping request: %v", err)
+    }
+
+    // Get certificate basic info
+    if fiskalEntity.IsExpiringSoon() {
+        fmt.Println("WARNING: Certificate is expiring soon")
+        fmt.Printf("Certificate expires in %d days",
+            fiskalEntity.DaysUntilExpire())
+    }
+
+    // Display certificate info
+    fmt.Println(fiskalEntity.DisplayCertInfoText())
+
+    invoice, zki, err := fiskalEntity.NewCISInvoice(
+        time.Now(),
+        uint(1236), // invoice number
+        uint(1),    // register id number
+        [][]interface{}{ // PDV
+            {"25.00", "1000.00", "250.00"},
+        },
+        nil, // PNP
+        nil, // Other taxes
+        "0.00", // total amount of exemptions on the issued invoice. 
+                // Exemptions in cases where goods are delivered or services are
+                // provided that are exempt from VAT payment.
+        "0.00", // amount subject to the special margin taxation procedure 
+                // if exist
+        "0.00", // total amount not subject to taxation on the issued invoice. 
+                // This information is submitted to the Tax Administration only
+                // if there is an amount on the invoice that is not subject to
+                // taxation.
+        nil,           // naknade
+        "1250.00",     // total
+        "G",           // payment method G - cash, K - credit card, T -
+                       // transfer, O - other, C - check (deprecated)
+        "12345678901", // operator OIB
+        false,         // late delivery, if previous attempt failed but the
+                       // invoice was issued with just ZKI
+        "",            // receipt book number, if the invoicing system was
+                       // unusable and the invoice was issued manually, the
+                       // number of the receipt book
+        "",            // unused, reserved field for future or temporary
+                       // unexpected use by the CIS, should be empty
+    )
+
+    if err != nil {
+        log.Fatalf("Failed to create invoice: %v", err)
+    }
+
+    // Display the ZKI
+    fmt.Println("ZKI: ", zki)
+
+    // At this point, the application can save the ZKI with the invoice and
+    // commit those changes. An invoice is valid with just ZKI and can be
+    // issued even if the next step fails and there is no JIR. But in that case,
+    // the process has to be repeated with the same identical data within 48h
+    // with the flag for late delivery set to true. A valid JIR has to be added
+    // within 48h to an invoice with just ZKI. It is recommended to save the
+    // serial of the certificate used to generate it for future reference. You
+    // can get the cert serial with fiskalEntity.GetCertSERIAL().
+
+    // Display the invoice
+    fmt.Println(invoice)
+
+    // NOW we should have a saved invoice with a valid ZKI and we are ready to
+    // send the invoice to the CIS
+
+    // Send test invoice to CIS with InvoiceRequest
+    jir, zkiR, err := fiskalEntity.InvoiceRequest(invoice)
+
+    if err != nil {
+        log.Fatalf("Failed to send invoice: %v", err)
+    }
+
+    // Display the JIR and ZKI
+    fmt.Println("JIR: ", jir)
+    fmt.Println("ZKI: ", zkiR)
+
+    // At this point the application can save the JIR with the invoice and
+    // commit those changes,
+
+    // Display/send/print the invoice to the user with all elements required by
+    // law
+}
+```
 
 ## Komercijalna i profesionalna podrška
 

diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@
 FiskalHR Go is a Go library designed for Croatian fiscalization (fiskalizacija). The goal of this library is to provide a well-maintained, efficient, and hassle-free solution with embedded certificates for checking signatures, making it easy to use.
 Based on ["Fiskalizacija" specification v2.5](https://www.porezna-uprava.hr/HR_Fiskalizacija/Documents/Fiskalizacija%20-%20Tehnicka%20specifikacija%20za%20korisnike_v2.5._23_10_23pdf.pdf)
 
-**Note:** This project is currently a work in progress and is not yet usable.
+**Note:** This project is currently a work in progress and alpha stage and not feature complete, not recommended in production but coming soon.
 
 [README in Croatian](README-HR.md)
 
@@ -22,21 +22,140 @@ Based on ["Fiskalizacija" specification v2.5](https://www.porezna-uprava.hr/HR_F
 - Process and send invoices to CIS (Croatian Tax Administration) for compliance the law.
 - Handle and verify responses from CIS.
 - Non-intrusive to the host application, leaving business logic entirely to the host.
-- Inform whether a response is validated against CIS public certificates without deciding what to do with unverified responses.
 - Parse and verify embedded certificates.
 - Parse and verify client P12 certificate.
 - Suitable for single tenant and multitenant application
 - Suitable for any type of application (web service, web app, desktop)
 - Extract and return certificate details such as public key, issuer, subject, serial number, and validity period.
-- Helper functions for generating QR code for printing on invoices in various formats
+- Helper function to get data for QR code (that can be passed to a QR code generator of your choice)
 
 ## Installation
 
-This project is not yet available for installation as it is still under development.
+In your project root get the module
+```
+go get github.com/l-d-t/fiskalhrgo
+```
 
 ## Usage
 
-Guide and documentation coming soon, when breaking changes stop and the library is feature complete
+Minimal simple example of CIS ping using the EchoRequest and get some cert info.
+
+Send a simple minimal invoice, get the JIR
+
+```go
+package main
+
+import (
+    "fmt"
+    "log"
+    "time"
+)
+
+func main() {
+    // Create a new FiskalEntity
+    fiskalEntity, err := NewFiskalEntity(
+        "12345678901", // OIB
+        true,          // sustavPDV
+        "Location1",   // locationID, if not DEMO MODE have to be registered
+                      // with ePorezna
+        true,          // centralized invoice numbers
+        true,          // demoMode, if true expected a valid Fiskal demo
+                      // certificate
+        true,          // chk_expired
+        "cert.p12",    // certPath
+        "password",    // certPassword
+    )
+    if err != nil {
+        log.Fatalf("Failed to create FiskalEntity: %v", err)
+    }
+
+    errPing := fiskalEntity.PingCIS()
+    if errPing != nil {
+        log.Fatalf("Failed to make Ping request: %v", err)
+    }
+
+    // Get certificate basic info
+    if fiskalEntity.IsExpiringSoon() {
+        fmt.Println("WARNING: Certificate is expiring soon")
+        fmt.Printf("Certificate expires in %d days",
+            fiskalEntity.DaysUntilExpire())
+    }
+
+    // Display certificate info
+    fmt.Println(fiskalEntity.DisplayCertInfoText())
+
+    invoice, zki, err := fiskalEntity.NewCISInvoice(
+        time.Now(),
+        uint(1236), // invoice number
+        uint(1),    // register id number
+        [][]interface{}{ // PDV
+            {"25.00", "1000.00", "250.00"},
+        },
+        nil, // PNP
+        nil, // Other taxes
+        "0.00", // total amount of exemptions on the issued invoice. 
+                // Exemptions in cases where goods are delivered or services are
+                // provided that are exempt from VAT payment.
+        "0.00", // amount subject to the special margin taxation procedure 
+                // if exist
+        "0.00", // total amount not subject to taxation on the issued invoice. 
+                // This information is submitted to the Tax Administration only
+                // if there is an amount on the invoice that is not subject to
+                // taxation.
+        nil,           // naknade
+        "1250.00",     // total
+        "G",           // payment method G - cash, K - credit card, T -
+                       // transfer, O - other, C - check (deprecated)
+        "12345678901", // operator OIB
+        false,         // late delivery, if previous attempt failed but the
+                       // invoice was issued with just ZKI
+        "",            // receipt book number, if the invoicing system was
+                       // unusable and the invoice was issued manually, the
+                       // number of the receipt book
+        "",            // unused, reserved field for future or temporary
+                       // unexpected use by the CIS, should be empty
+    )
+
+    if err != nil {
+        log.Fatalf("Failed to create invoice: %v", err)
+    }
+
+    // Display the ZKI
+    fmt.Println("ZKI: ", zki)
+
+    // At this point, the application can save the ZKI with the invoice and
+    // commit those changes. An invoice is valid with just ZKI and can be
+    // issued even if the next step fails and there is no JIR. But in that case,
+    // the process has to be repeated with the same identical data within 48h
+    // with the flag for late delivery set to true. A valid JIR has to be added
+    // within 48h to an invoice with just ZKI. It is recommended to save the
+    // serial of the certificate used to generate it for future reference. You
+    // can get the cert serial with fiskalEntity.GetCertSERIAL().
+
+    // Display the invoice
+    fmt.Println(invoice)
+
+    // NOW we should have a saved invoice with a valid ZKI and we are ready to
+    // send the invoice to the CIS
+
+    // Send test invoice to CIS with InvoiceRequest
+    jir, zkiR, err := fiskalEntity.InvoiceRequest(invoice)
+
+    if err != nil {
+        log.Fatalf("Failed to send invoice: %v", err)
+    }
+
+    // Display the JIR and ZKI
+    fmt.Println("JIR: ", jir)
+    fmt.Println("ZKI: ", zkiR)
+
+    // At this point the application can save the JIR with the invoice and
+    // commit those changes,
+
+    // Display/send/print the invoice to the user with all elements required by
+    // law
+}
+```
 
 ## Commercial and Professional Support