fiscalizer 0.0.12 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b3d926aeb8f7660653b31e50f8f6d9cb0d6ce358
-  data.tar.gz: 07932327e37b033a5f728fbc070ed1ba8b66bfc7
+  metadata.gz: cc259947daa868463b0de723f158b9f4d5b46dc5
+  data.tar.gz: 1fe536eca7ea1a013f819c26c1ccfffd2aead82d
 SHA512:
-  metadata.gz: 609ed055f9da766bf912707ea1c825c627a301ac6d5a23626f2678a836b455852d1aafac90172c673d00bc83d6eb155791d3b92bb364ad227cbcf11e2f4f26a2
-  data.tar.gz: 2ba0fa751aa803e5a37ddc58462a1ee3306e509c4473d49100e9b2cfcbdbae821a08cc6507586a203b375556a7fdfb6c637488493ac3a180b5821d0bcbf012e6
+  metadata.gz: 1249e0e6e1d45c5ce5115e562e0f903336eb16e0ee41a8a27b3c0617808a6b5d342ed774d04218d13ca8cb0089ce974558d31da212fdec910fb1ad7600855afc
+  data.tar.gz: 37fab01aaec2515768621f022356b6722af529e1aa425166557b26670fc4ae5a5898f261de1f4c9f89e6e4be45d668353e797a2844aa5eabc9e872a3f3573cc4

data/.gitignore

@@ -14,4 +14,5 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
-test/assets/*
+test/assets/*
+certificates

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -1,7 +1,3 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in fiscalizer_ruby.gemspec
 gemspec
-gem 'nokogiri'
-gem 'xmldsig-fiscalizer'
-#gem 'pry-debugger'

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Infinum
+Copyright (c) 2017 Infinum
 
 MIT License
 

data/README.md

@@ -2,19 +2,9 @@
 
 ## Introduction
 
-Fiscalization is the process of transfering various document types from a business entity to the tax authorities with the goal of reducing tax fraud. In Croatia this process can be executed over the Internet, this gem is intended to automate this process.
+Fiscalization is the process of transferring various document types from a business entity to the tax authorities with the goal of reducing tax fraud. In Croatia this process can be executed over the Internet and this gem is intended to automate the process.
 
-## Documentation
-
-Every folder has it's own README file which explanes in detail the files in it.
-
-Examples are located in the `example` folder. Basic setup and fiscalization are demonstrated here.
-
-Tests are located in the `test` folder. Test setup is explaned there.
-
-All classes, in their separate files, are located in the `fiscalizer` folder.
-
-## Instalation
+## Installation
 
 Add this line to your application's Gemfile:
 
@@ -29,181 +19,207 @@ Or install it yourself as:
     $ gem install fiscalizer
 
 ## Usage
-### Setup
-To use Fiscalizer in your projects simply call `fiscalizer = Fiscalizer.new`, this will create a new fiscalizer object for you to interact with.
 
-Necessary parameters, that have to be set before any fiscalization occures are:
+### Setup
+To use Fiscalizer initialize a new Fiscalizer object (`fiscalizer = Fiscalizer.new`) with these arguments:
 
- * `certificate_p12_path` : Path to your fiscal certificate (usually "FISCAL 1.p12" or "fiscal1.pfx")
+ * `app_cert_path` : Path to your fiscal certificate. (usually "FISCAL_1.p12" or "fiscal1.pfx")
  * `password` : Password that unlocks the certificate
 
-Alternatively you can set these three parameters:
+Optional argument is:
+
+ * `timeout` : Specifies the number of seconds to wait for Fiscalization server to respond. (defaults to 3)
+
+Example:
 
- * `key_public_path` : Path to the public key ( "fiskal1.cert" )
- * `key_private_path` : Path to the private key ( "privateKey.key" )
- * `certificate_path` : Path to the certificate ( "certificate.pem" )
+```ruby
+fiscalizer = Fiscalizer.new(
+  app_cert_path: 'path/to/FISCAL_1.p12',
+  password: 'password',
+  timeout: 4
+)
+```
+#### Demo environment
 
-__NOTE:__ Thise parameters will override the parameters extracted from the P12 certificate!
+If Fiscalizer is used in demo (test) environment, you need to set 2 additional parameters when initializing `Fiscalizer` object:
 
-Parameters that can also be set:
+* `demo` : Specifies that Fiscalizer should send requests to FINA DEMO server. (boolean)
+* `ca_cert_path` : Specifies the path to trusted CA certificates. This file should contain both FINA ROOT CA certificate and FINA DEMO CA certificate. (usually called "fina_ca.pem")
 
- * `url` : Specifies the URL to which the requests will be sent ( defaults to "https://cis.porezna-uprava.hr:8449/FiskalizacijaService")
- * `tns` : Specifies the XML namespaces to use when parsing and encoding objects ( defaults to "http://www.apis-it.hr/fin/2012/types/f73")
- * `schemaLocation` : Specifies the XML schema to be used for XML parsing ( defualts to "http://www.apis-it.hr/fin/2012/types/f73 FiskalizacijaSchema.xsd")
- * `certificate_issued_by` : Certificate issuer identifier to be used in the signature ( defaults to "OU=RDC,O=FINA,C=HR")
+Example:
+
+```ruby
+fiscalizer = Fiscalizer.new(
+  app_cert_path: 'path/to/FISCAL_1.p12',
+  password: 'password',
+  demo: true,
+  ca_cert_path: 'path/to/fina_ca.pem'
+)
+```
 
 ### Fiscalization
 
-This gem offers two types of fiscalization, _Office space_ and _Invoice_ fiscalization. _Echo_ requests are also possible.
-
-All these methods return an `Fiscalizer::Response` object, which is explaned below.
-
-#### Invoices
-
-To fiscalize an invoice call `fiscalizer.fiscalize_invoice` and pass it an `Fiscalizer::Invoice` object.
-
-Alternatively it is possible to pass all the arguments needed to build an invoice, this will build an invoice
-and fiscalize it automatically.
-
-Arguments that can be passed to `fiscalizer.fiscalize_invoice`:
-
- * `uuid` : Universally Unique Identifier (String)
- * `time_sent` : Time the invoice fiscalization request was sent (Time)
- * `pin` : The fiscal entitie's PIN number (String)
- * `in_vat_system` : Specifies if the fical entity is in the VAT system (Boolean)
- * `time_issued` : Time the invoice was created (Time)
- * `consistance_mark` : Character that specifes where the invoice was issued, "P" for _Office space_ or "N" for _Payment machine_ (String)
- * `issued_number` : Nummerical invoice identifier (String ot Integer)
- * `issued_office` : Office space identifier where the invoice was issued (String)
- * `issued_machine` : Numerical payment machine identifier (String or Integer)
- * `tax_vat` : Array containing all VAT taxes (Array containing _Fiscalizer::Tax_ objects)
- * `tax_spending` : Array containing all spending taxes (Array containing _Fiscalizer::Tax_ objects)
- * `tax_other` : Array containing all other taxes (Array containing _Fiscalizer::Tax_ objects)
- * `value_tax_liberation` : Ammount that will be submitted for tax liberation (Float)
- * `value_tax_margin` : Ammount that will be subjected to the special tax margin process (Float)
- * `value_non_taxable` : Ammount that isn't subject to any taxing (Float)
- * `fees` : Array containing all fees (Array containing _Fiscalizer::Fee_ objects)
- * `summed_total` : Summed total price of the invoice (Float)
- * `payment_method` : Specifies the payment method, "G" for cash, "K" for card, "C" for check, "T" for transaction, "O" for other (String)
- * `operator_pin` : The PIN number of the person issuing the invoice (String)
- * `security_code` : Security code of the invoice (String)
- * `subsequent_delivery` : Subsequent delivery mark (Boolean)
- * `paragon_label` : Paragon label for invoices that have to be fiscalized after the office space or payment machine has been removed from the fiscalization system (String)
- * `specific_purpose` : This is an additional label in case of further expansion of the fiscalization system (String)
- * `unique_identifier` : Unique identifier of the invoice (String)
- * `reconnect_attempts` : Specifies how many times to try establishing a connection, defaults to 3 (Integer)
-
-__Note:__ `summed_total` will return the sum of all taxed values from `tax_vat`, `tax_spending`, `tax_other`
-
-#### Office spaces
-
-To fiscalize an office space call `fiscalizer.fiscalize_office` and pass it an `Fiscalizer::Office` object.
-
-Arguments that can be passed to `fiscalizer.fiscalize_office`:
-
- * `uuid` : Universally Unique Identifier (String)
- * `time_sent` : Time the office space fiscalization request was sent (Time)
- * `pin` : The fiscal entitie's PIN number (String)
- * `office_label` : Office space identifier string (String)
- * `adress_street_name` : Name of the street the where the office space is located (String)
- * `adress_house_num` : House number of the office space (String)
- * `adress_house_num_addendum` : Additional house number of the office space, eg.: "a" or "3/4" (String)
- * `adress_post_num` : Post office number of the office space (String)
- * `adress_settlement` : Settlement name of the office space's location (String)
- * `adress_township` : Township name of the office space's location (String)
- * `adress_other` : Field to specify non standart office spaces, eg.: "web store" (String)
- * `office_time` : Specifies the working hours of the office space, anything is valid (String)
- * `take_effect_date` : Date from which the change takes effect (Time)
- * `closure_mark` : Mark that indicates the cloasure of the office space, send "Z" to close (String)
- * `specific_purpose` : Software manufacturer's PIN number (String)
- * `reconnect_attempts` : Specifies how many times to try establishing a connection, defaults to 3 (Integer)
-
-#### Echo requests
-
-Even though echo requests are not particularly usefull for fiscalization they are described in the API and
-therefore they are also implemented.
-
-To make an echo request call `fiscalizer.echo` and eather pass it na `Fiscalizer::Echo` object or `text: "Your echo text"`
-as an argument.
-
-#### Responses
-
-Response objects are perhaps the most important objects in this Gem.
-They contain pre-parsed information that was returned from the fiscalization servers.
-
-Methods:
- * `type` : Type of the response, 0-Error, 1-Echo, 2-Office, 3-Invoice (Integer)
- * `errors` : Hash containg all errors returned from the server, the key is the error code, and the value is the error explanation (Hash)
- * `object` : Holds the object that generated the response (Echo, Invoice, Office)
- * `uuid` : UUID returned by the server (String)
- * `processed_at` : Time the request was processed (Time)
- * `response` : Text returned in an Echo message (String)
- * `unique_identifier` : Unique invoice identifier (String)
- * `tns` : TNS used to parse the XML responses (String)
- * `html_response` : Raw HTML response (HTTP::Response)
- * `generated_xml` : XML generated for the reqest to which this response belongs (String)
- * `has_error` : Returns true if there are any arrors (Boolean), alia method `errors?`
- * `error_codes` : Returns all error codes in an array (Array containing String)
- * `error_messages` : Returns all error messages in an array (Array containing String)
- * `type_str` : Returnes the response type as a string (String)
- * `echo_succeeded` : Returns true if echo message sent and returned are the same (Boolean)
-
-# Notes
-
-The public and private keys, and signing certificate are automatically extracted from a P12 certificate.
-But the same is not true for a PFX certificate! PFX certificates don't contain a signing certificate and
-therefore one has to be passed as an argument (`certificate_path`) additionaly to the PFX certificate (`certificate_p12_path`)
-
-Direct usage of the `Fiscalizer::Communication` class is not advised!
-
-# Translations
-
- * __uuid__ : UUID
- * __time_sent__ : Datum i vrijeme slanja
- * __pin__ : OIB
- * __office_label__ : Oznaka poslovnog prostora
- * __adress_street_name__ : Ime ulice
- * __adress_house_num__ : Kućni broj
- * __adress_house_num_addendum__ : Dodatak kućnom broju
- * __adress_post_num__ : Broj pošte
- * __adress_settlement__ : Nasenje
- * __adress_township__ : Općina
- * __adress_other__ : Ostali tipovo poslovnog porstora
- * __office_time__ : Radno vrijeme
- * __take_effect_date__ : Datum početka primjene
- * __closure_mark__ : Oznaka zatvaranja
- * __specific_purpose__ : Specifična namjena
- * __in_vat_system__ : U sustavu PDVa
- * __time_issued__ : Datum i vrijeme izdavanja
- * __consistance_mark__ : Oznaka slijednosti
- * __issued_number__ : Brojčana oznaka računa
- * __issued_office__ : Oznaka poslovnog prostora
- * __issued_machine__ : Oznaka naplatnog uređaja
- * __tax_vat__ : PDV
- * __tax_spending__ : PNP 
- * __tax_other__ : Ostali porezi
- * __value_tax_liberation__ : Iznos oslobođenja
- * __value_tax_margin__ : Iznos koji se odnosi na poseban postupak oporezivanja marže
- * __value_non_taxable__ : Iznos koji ne podlježe oporezivanju
- * __fees__ : Naknade
- * __summed_total__ : Ukupan iznos
- * __payment_method__ : Način plaćanja
- * __operator_pin__ : OIB operatera
- * __security_code__ : Zaštitni kod izdavatelja (ZKI)
- * __subsequent_delivery__ : Oznaka nadoknadne dostave
- * __paragon_label__ : Oznaka paragon računa
- * __specific_purpose__ : Specifična namjena
- * __unique_identifier__ : Jedinstveni identifikator računa (JIR)
- * __base__ : Osnovica
- * __rate__ : Porezna stopa
+Ficalizer class provides 3 public methods:
+
+* `echo(message)`
+* `fiscalize_invoice(invoice)`
+* `fiscalize_office(office)`
+
+#### Echo
+
+Echo method receives a message, sends it to the Fiscalization server and returns the echo response:
+
+```ruby
+response = fiscalizer.echo('Echo message')
+response.success? # true
+response.echo_response # Echo message
+```
+
+#### Invoice
+
+To fiscalize the invoice, you first need to create a `Fiscalizer::Invoice` object and pass it to the `fiscalize_invoice` method.
+
+Before the fiscalization process starts, a `security_code` (ZKI) will be automatically generated and assigned to invoice.
+If the fiscalization process is successful, response will contain a `unique_identifier` (JIR). Else, it will contain an array with errors (each error is a hash with `code` and `message`).
+
+`Fiscalizer::Invoice` object can be initialized with the following arguments:
+
+ * `uuid` : Universally Unique Identifier / ID poruke (String, required)
+ * `time_sent` : Time the invoice fiscalization request was sent / Datum i vrijeme slanja (DateTime in format dd.mm.yyyyThh:mm:ss, required)
+ * `pin` : The fiscal entitie's PIN number / OIB obveznika fiskalizacije (String, required)
+ * `in_vat_system` : Specifies if the fical entity is in the VAT system / U sustavu PDV (Boolean, required)
+ * `time_issued` : Time the invoice was created / Datum i vrijeme izdavanja (DateTime, required)
+ * `consistance_mark` : Character that specifes where the invoice was issued, "P" for _Office space_ or "N" for _Payment machine_ / Oznaka slijednosti (String, required)
+ * `issued_number` : Numerical invoice identifier / Brojčana oznaka računa (0-9) (String/Integer, required)
+ * `issued_office` : Office space identifier where the invoice was issued / Oznaka poslovnog prostora (String, required)
+ * `issued_machine` : Numerical payment machine identifier / Oznaka naplatnog uređaja (String/Integer, required)
+ * `tax_vat` : Array containing all VAT taxes / Porez na dodanu vrijednost (Array containing _Fiscalizer::Tax_ objects, optional)
+ * `tax_spending` : Array containing all spending taxes / Porez na potrošnju (Array containing _Fiscalizer::Tax_ objects, optional)
+ * `tax_other` : Array containing all other taxes / Ostali porezi (Array containing _Fiscalizer::Tax_ objects, optional)
+ * `value_tax_liberation` : Amount that will be submitted for tax liberation / Iznos oslobođenja (Float, optional)
+ * `value_tax_margin` : Amount that will be subjected to the special tax margin process / Iznos na koji se odnosi poseban postupak oporezivanja marže (Float, optional)
+ * `value_non_taxable` : Amount that isn't subject to any taxing / Iznos koji ne podliježe oporezivanju (Float, optional)
+ * `fees` : Array containing all fees / Naknade (Array containing _Fiscalizer::Fee_ objects, optional)
+ * `summed_total` : Summed total price of the invoice / Ukupan iznos (Float, required)
+ * `payment_method` : Specifies the payment method, "G" for cash, "K" for card, "C" for check, "T" for transaction, "O" for other / Način plaćanja (String, required)
+ * `operator_pin` : The PIN number of the person issuing the invoice / OIB operatera na naplatnom uređaju (String, required)
+ * `subsequent_delivery` : Subsequent delivery mark / Oznaka naknadne dostave računa (Boolean, required)
+ * `paragon_label` : Paragon label for the invoice that have to be fiscalized after the office space or payment machine has stopped working / Oznaka paragon računa (String, optional)
+ * `specific_purpose` : This is an additional label in case of further expansion of the fiscalization system / Specifična namjena (String, optional)
+
+ After the fiscalization process, response object contains these informations:
+
+ * `raw_response` : XML with the raw response from the Fiscalization server
+ * `uuid` : UUID of the response
+ * `processed_at` : DateTime when the fiscalization is processed
+ * `unique_identifier` : Unique fiscalization identifier of the invoice (JIR) (can be nil if there were errors)
+ * `errors?` : Boolean indicating if there were any errors during the process
+ * `errors` : Array containing errors if any - Each error is a hash with `code` and `message`
+
+ Fiscalizer invoice object contains these informations after the fiscalization:
+
+ * `security_code` : Security code of the invoice (ZKI)
+ * `generated_xml` : XML that was sent to the Fiscalization server
+
+ Example:
+
+ ```ruby
+ invoice = YourApp::Invoice.find(...)
+ fiscalizer_invoice = Fiscalizer::Invoice.new(...) # convert your invoice to fiscalizer invoice
+ fiscalizer = Fiscalizer.new(
+   app_cert_path: 'path/to/FISCAL_1.p12',
+   password: 'password'
+ )
+
+ begin
+   response = fiscalizer.fiscalize_invoice(fiscalizer_invoice)
+   fail 'Fiscalization error' if response.errors? # or do something with the errors
+
+   invoice.update(jir: response.unique_identifier)
+ ensure
+   invoice.update(
+     fiscalization_response: response.raw_response,
+     fiscalization_request: fiscalizer_invoice.generated_xml,
+     zki: fiscalizer_invoice.security_code,
+     errors: response.errors
+   )
+ end
+ ```
+
+#### Taxes and Fees
+
+When initializing `Fiscalizer::Invoice`, you can set multiple taxes, as indicated above. Those taxes need to be instances of `Fiscalizer::Tax` class.
+
+`Fiscalizer::Tax` object can be initialized with the following arguments:
+
+* `base` : Base amount / Iznos osnovice (Float, required)
+* `rate` : Tax rate / Porezna stopa (Float, required)
+* `name` : Tax name / Naziv poreza (String, required)
+
+Also, you can set multiple fees for the invoice. Fee need to be instance of the `Fiscalizer::Fee` class.
+
+`Fiscalizer::Fee` object can be initialized with the following arguments:
+
+* `name` : Fee name / Naziv naknade (String, required)
+* `value` : Fee amount / Iznos naknade (Float, required)
+
+#### Office
+
+To fiscalize the office space, you first need to create a `Fiscalizer::Office` object and pass it to the `fiscalize_office` method.
+
+`Fiscalizer::Office` object can be initialized with the following arguments:
+
+ * `uuid` : Universally Unique Identifier / ID poruke (String, required)
+ * `time_sent` : Time the office space fiscalization request was sent / Datum i vrijeme slanja (DateTime, required)
+ * `pin` : The fiscal entitie's PIN number / OIB obveznika fiskalizacije (String, required)
+ * `office_label` : Office space identifier / Oznaka poslovnog prostora (String, required)
+ * `adress_street_name` : Street name of the office space / Ulica (String, required if `address_other` is not set)
+ * `adress_house_num` : House number of the office space / Kućni broj (String, required if `address_other` is not set)
+ * `adress_house_num_addendum` : Additional house number of the office space, eg.: "a" or "3/4" / Dodatak kućnom broju (String, optional)
+ * `adress_post_num` : Post office number of the office space / Broj pošte (String, required if `address_other` is not set)
+ * `adress_settlement` : Settlement name of the office space's location / Naselje (String, optional)
+ * `adress_township` : Township name of the office space's location / Naziv općine ili grada (String)
+ * `adress_other` : Field to specify non standard office spaces, eg.: "web store" / Ostali tipovi poslovnog prostora (String, optional)
+ * `office_time` : Specifies the working hours of the office space / Radno vrijeme (String, required)
+ * `take_effect_date` : Date from which the change takes effect / Datum početka primjene (Date, required)
+ * `closure_mark` : Mark that indicates the closure of the office space, send "Z" to close / Oznaka zatvaranja (String, optional)
+ * `specific_purpose` : Software manufacturer's PIN number / Specifična namjena (String, optional)
+
+ After the fiscalization process, response object contains these informations:
+
+ * `raw_response` : XML with the raw response from the Fiscalization server
+ * `uuid` : UUID of the response
+ * `processed_at` : DateTime when the fiscalization is processed
+ * `errors?` : Boolean indicating if there were any errors during the process
+ * `errors` : Array containing errors if any - Each error is a hash with `code` and `message`
+
+ Example:
+
+ ```ruby
+ fiscalizer_office = Fiscalizer::Office.new(...)
+ fiscalizer = Fiscalizer.new(
+   app_cert_path: 'path/to/FISCAL_1.p12',
+   password: 'password'
+ )
+
+ response = fiscalizer.fiscalize_office(fiscalizer_office)
+
+ # do something with the response
+ ```
+
+# Fiscalization specification
+
+The official technical specification for the Fiscalization process can be found
+[here](https://www.porezna-uprava.hr/HR_Fiskalizacija/Stranice/Tehni%C4%8Dke-specifikacije.aspx).
 
 # Credits
 
 Fiscalizer is maintained and sponsored by
-[Infinum](http://www.infinum.co).
+[Infinum](https://infinum.co/).
 
-![Infinum](http://www.infinum.co/system/logo.png)
+![Infinum](https://camo.githubusercontent.com/ce804b9555629d79335cf51c0bd6aedc615aeb3f/68747470733a2f2f696e66696e756d2e636f2f696e66696e756d2e706e67)
 
 # License
 
-Phrasing is Copyright © 2014 Infinum. It is free software, and may be redistributed under the terms specified in the LICENSE file.
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "fiscalizer"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require "pry"
+Pry.start
+
+# require "irb"
+# IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here