szamlazz 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9c183273cd106d85bd38f852d4812c04f7bc30e8f5814d9b535f3f5cdd4f588
+  data.tar.gz: 02014ba8e63ea6ccad36e74f369173807e25a1bcbf387cace998f43bb9f9ce2f
+SHA512:
+  metadata.gz: 7ff20a1120ac457030701ffa4ef13ddbdda6af91c13455f860501d2afcde918c92f737d4c8d216b3c68fc04417ab83f23b14b6e10e22524cae91823fc3fb9a7a
+  data.tar.gz: 50ea5230beaa41088ccec36c205389dd8679adcba2992123fc274dffada6802753d28c8fd3119c4478afe56f69f059cf0bcbacdd20e3cf12a614e4e5637fa14a

data/lib/inflections.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+ActiveSupport::Inflector.inflections do |inflect|
+  # This is the pluralization of a Hungarian word (literally: line item). It
+  # helps us with our Hash#to_xml method in CreateInvoice, since that has an
+  # array called line items ('tetelek'), which should have children called
+  # line item ('tetel').
+  inflect.irregular 'tetel', 'tetelek'
+end

data/lib/pdf_validator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# A crude validator for PDF files.
+class PDFValidator
+  # ISO 32000-1:2008 Section 7.5.2. states:
+  # "The first line of a PDF file shall be a header consisting of the 5
+  # characters %PDF-"
+  #
+  # This is not proof that the contents describe a PDF file, but it's a good
+  # approximation.
+  def self.valid?(string)
+    string.start_with?('%PDF-')
+  end
+end

data/lib/szamlazz.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+require 'szamlazz/version'
+require 'szamlazz/szamlazz_error'
+require 'szamlazz/create_invoice'
+
+# Base wrapper class for the gem.
+# Initialize with login information to your szamlazz.hu account.
+class Szamlazz
+  include CreateInvoice
+
+  DEFAULT_ENDPOINT = 'https://www.szamlazz.hu/szamla/'
+
+  def initialize(user:, password:, endpoint: nil)
+    @user = user
+    @password = password
+    @endpoint = URI.parse(endpoint || DEFAULT_ENDPOINT)
+  end
+end

data/lib/szamlazz/create_invoice.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash'
+require 'net/http'
+require 'tempfile'
+
+require 'inflections'
+require 'pdf_validator'
+require 'szamlazz/create_invoice/default_options'
+require 'szamlazz/create_invoice/key_translations'
+
+class Szamlazz
+  # Creates and downloads the string representation of a PDF invoice.
+  module CreateInvoice
+    HTTP_FORM_FIELD_NAME = 'action-xmlagentxmlfile'
+    HTTP_MEDIA_TYPE = 'multipart/form-data'
+    XML_ROOT_ELEMENT = <<~XML
+      <xmlszamla
+        xmlns="http://www.szamlazz.hu/xmlszamla"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="
+          http://www.szamlazz.hu/xmlszamla
+          http://www.szamlazz.hu/docs/xsds/agent/xmlszamla.xsd
+        "
+      >
+    XML
+
+    def create_invoice(options = {})
+      options = default_options.deep_merge(options)
+      structured_options = create_api_structure(XML_TREE_TRANSLATIONS, options)
+      xml_string = create_xml_string(structured_options)
+      # TODO: find a better way to send our payload. We shouldn't need to create
+      # this Tempfile. Maybe something with StringIO?
+      xml_file = create_xml_file(xml_string)
+      response = send_request(xml_file)
+
+      check_for_api_failure(response)
+      check_if_response_is_pdf(response)
+
+      response.body
+    end
+
+    private
+
+    def default_options
+      DEFAULT_OPTIONS.deep_merge(settings: { user: @user, password: @password })
+    end
+
+    # This function actually doesn't seem that excessively large for a
+    # recursive function. It has 3 fairly simple cases - still, it might be
+    # valuable to refactor it and/or the whole API structure creation.
+    # rubocop:disable Metrics/MethodLength
+    def create_api_structure(root, options)
+      ret = {}
+
+      root.each do |element|
+        option = options[element.input_name]
+        next if option.nil?
+
+        ret[element.output_name] =
+          if option.is_a?(Hash)
+            create_api_structure(element, option)
+          elsif option.is_a?(Array)
+            option.map do |new_option|
+              create_api_structure(element.first, new_option)
+            end
+          else
+            option
+          end
+      end
+
+      ret
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    def create_xml_string(options)
+      # TODO: find a better way to give attributes to our root element.
+      # Preferably one that doesn't import additional dependencies.
+      options.to_xml(skip_types: true, root: 'xmlszamla')
+             .sub('<xmlszamla>', XML_ROOT_ELEMENT)
+    end
+
+    def create_xml_file(string)
+      tempfile = Tempfile.new(['invoice', '.xml'])
+      tempfile.write(string)
+      tempfile.close
+
+      tempfile
+    end
+
+    def send_request(xml_file)
+      request = Net::HTTP::Post.new(@endpoint)
+      request.set_form([[HTTP_FORM_FIELD_NAME, xml_file.open]], HTTP_MEDIA_TYPE)
+
+      Net::HTTP.start(@endpoint.hostname,
+                      @endpoint.port,
+                      use_ssl: true) do |http|
+        http.request(request)
+      end
+    end
+
+    def check_for_api_failure(response)
+      return unless response['szlahu_error'] || response['szlahu_error_code']
+
+      # TODO: these errors are in Hungarian. It's not currently a priority to
+      # get them in English, but some time in the future it may be good to
+      # internationalize them somehow.
+      #
+      # Also, the error message usually includes the full stack trace of the
+      # API provider's error. This may be distracting to our use case.
+      raise SzamlazzError, <<~ERROR
+        Error Code: #{response['szlahu_error_code']}
+        Error: #{response['szlahu_error']}
+      ERROR
+    end
+
+    def check_if_response_is_pdf(response)
+      return if PDFValidator.valid?(response.body)
+
+      raise SzamlazzError, <<~ERROR
+        Error Code: -1
+        Error: The API did not return a valid PDF for unknown reasons.
+      ERROR
+    end
+  end
+end

data/lib/szamlazz/create_invoice/default_options.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class Szamlazz
+  module CreateInvoice
+    DEFAULT_OPTIONS = {
+      settings:   {
+        # User and password should be updated at request time.
+        user:             '',
+        password:         '',
+        e_invoice:        false,
+        download_invoice: true
+      },
+      header:     {
+        date_of_issue:    Date.today,
+        completion_date:  Date.today,
+        due_date:         Date.today,
+        # TODO: solve translation for localized values.
+        payment_method:   'Átutalás',
+        currency:         'HUF',
+        invoice_language: 'hu'
+      },
+      seller:     {},
+      customer:   {
+        name:     'Placeholder Name',
+        zip_code: 'Placeholder ZIP',
+        city:     'Placeholder City',
+        address:  'Placeholder Address'
+      },
+      line_items: [
+        {
+          line_item_name:      'Placeholder LineItemName',
+          quantity:            1,
+          # TODO: solve translation for localized values.
+          unit_of_measurement: 'db',
+          unit_price:          100,
+          vat_rate:            27,
+          net_price:           100,
+          vat_value:           27,
+          gross_price:         127
+        }
+      ]
+    }.freeze
+  end
+end

data/lib/szamlazz/create_invoice/key_translations.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'szamlazz/translation_node'
+
+class Szamlazz
+  # rubocop:disable all
+  module CreateInvoice
+    # Learn the functionality of these keys in the API documentation.
+    # There's a list of required keys in DEFAULT_OPTIONS.
+
+    def self.tn(input_name, output_name, children = [])
+      TranslationNode.new(
+        input_name:  input_name,
+        output_name: output_name,
+        children:    children
+      )
+    end
+
+    XML_TREE_TRANSLATIONS =
+      tn(:root, :xmlszamla, [
+           tn(:settings, :beallitasok, [
+                tn(:user, :felhasznalo),
+                tn(:password, :jelszo),
+                tn(:e_invoice, :eszamla),
+                tn(:keyring_password, :kulcstartojelszo),
+                tn(:download_invoice, :szamlaLetoltes),
+                tn(:number_of_copies, :szamlaLetoltesPld),
+                # This gem depends on this value being the default (1).
+                tn(:response_version, :valaszVerzio),
+                tn(:aggregator, :aggregator)
+              ]),
+
+           tn(:header, :fejlec, [
+                tn(:date_of_issue, :keltDatum),
+                # Sic: if the invoice is generated in English, this value is
+                # labelled as 'Completion date'.
+                tn(:completion_date, :teljesitesDatum),
+                tn(:due_date, :fizetesiHataridoDatum),
+                tn(:payment_method, :fizmod),
+                tn(:currency, :penznem),
+                tn(:invoice_language, :szamlaNyelve),
+                tn(:description, :megjegyzes),
+                tn(:exchange_bank, :arfolyamBank),
+                tn(:exchange_rate, :arfolyam),
+                tn(:order_number, :rendelesSzam),
+                tn(:prepayment_invoice, :elolegszamla),
+                tn(:final_invoice, :vegszamla),
+                tn(:correcting_invoice, :helyesbitoszamla),
+                tn(:corrected_invoice_number, :helyesbitettSzamlaszam),
+                tn(:pro_forma_invoice, :dijbekero),
+                tn(:delivery_note, :szallitolevel),
+                tn(:logo_extra, :logoExtra),
+                tn(:invoice_number_prefix, :szamlaszamElotag),
+                tn(:correction_amount, :fizetendoKorrekcio),
+                tn(:paid, :fizetve),
+                tn(:vat_margin, :arresAfa)
+              ]),
+
+           tn(:seller, :elado, [
+                tn(:bank, :bank),
+                tn(:bank_account_number, :bankszamlaszam),
+                tn(:email_reply_to, :emailReplyto),
+                tn(:email_subject, :emailTargy),
+                tn(:email_text, :emailSzoveg),
+                tn(:signatory_name, :alairoNeve)
+              ]),
+
+           tn(:customer, :vevo, [
+                tn(:name, :nev),
+                tn(:country, :orszag),
+                tn(:zip_code, :irsz),
+                tn(:city, :telepules),
+                tn(:address, :cim),
+                tn(:email, :email),
+                tn(:send_email, :send_email),
+                tn(:taxable_person, :adoalany),
+                tn(:tax_id_number, :adoszam),
+                tn(:tax_id_number_eu, :adoszamEU),
+                tn(:shipping_name, :postazasiNev),
+                tn(:shipping_country, :postazasiOrszag),
+                tn(:shipping_zip_code, :postazasiIrsz),
+                tn(:shipping_city, :postazasiTelepules),
+                tn(:shipping_address, :postazasiCim),
+                tn(:customer_general_ledger, :vevoFokonyv, [
+                     tn(:journal_entry_date, :konyvelesiDatum),
+                     tn(:customer_identifier, :vevoAzonosito),
+                     tn(:customer_general_ledger_account_number, :vevoFokonyviSzam),
+                     tn(:recurring_billing, :folyamatosTelj)
+                   ]),
+                tn(:identifier, :azonosito),
+                tn(:signatory_name, :alairoNeve),
+                tn(:phone_number, :telefonszam),
+                tn(:note, :megjegyzes)
+              ]),
+
+           tn(:waybill, :fuvarlevel, [
+                tn(:ship_to, :uticel),
+                tn(:carrier, :futarSzolgalat),
+                tn(:bar_code, :vonalkod),
+                tn(:note, :megjegyzes),
+                tn(:tof, :tof, [
+                     tn(:identifier, :azonosito),
+                     tn(:shipment_id, :shipmentID),
+                     tn(:number_of_packages, :csomagszam),
+                     tn(:country_code, :countryCode),
+                     tn(:zip, :zip),
+                     tn(:service, :service)
+                   ]),
+                tn(:ppp, :ppp, [
+                     tn(:bar_code_prefix, :vonalkodPrefix),
+                     tn(:bar_code_postfix, :vonalkodPostfix)
+                   ]),
+                tn(:sprinter, :sprinter, [
+                     tn(:identifier, :azonosito),
+                     tn(:sender_code, :feladokod),
+                     tn(:zip_code, :iranykod),
+                     tn(:number_of_packages, :csomagszam),
+                     tn(:bar_code_postfix, :vonalkodPostfix),
+                     tn(:shipping_time, :szallitasiIdo)
+                   ]),
+                tn(:mlp, :mlp, [
+                     tn(:customer_code, :vevokod),
+                     tn(:bar_code, :vonalkod),
+                     tn(:weight, :tomeg),
+                     tn(:additional_services, :kulonszolgaltatasok),
+                     tn(:insured_value, :erteknyilvanitas)
+                   ])
+              ]),
+
+           tn(:line_items, :tetelek, [
+                tn(:line_item, :tetel, [
+                     tn(:line_item_name, :megnevezes),
+                     tn(:identifier, :azonosito),
+                     tn(:quantity, :mennyiseg),
+                     tn(:unit_of_measurement, :mennyisegiEgyseg),
+                     tn(:unit_price, :nettoEgysegar),
+                     tn(:vat_rate, :afakulcs),
+                     tn(:vat_margin_base, :arresAfaAlap),
+                     tn(:net_price, :nettoErtek),
+                     tn(:vat_value, :afaErtek),
+                     tn(:gross_price, :bruttoErtek),
+                     tn(:description, :megjegyzes),
+                     tn(:line_item_general_ledger, :tetelFokonyv, [
+                          tn(:accounting_event, :gazdasagiEsem),
+                          tn(:accounting_event_vat, :gazdasagiEsemAfa),
+                          tn(:revenue_general_ledger_account_number, :arbevetelFokonyviSzam),
+                          tn(:vat_general_ledger_account_number, :afaFokonyviSzam),
+                          tn(:accounting_period_from, :elszDatumTol),
+                          tn(:accounting_period_to, :elszDatumIg)
+                        ])
+                   ])
+              ])
+         ])
+  end
+  # rubocop:enable all
+end

data/lib/szamlazz/szamlazz_error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Raised when the server read the API request but did not fulfill it.
+class SzamlazzError < StandardError; end

data/lib/szamlazz/translation_node.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+class Szamlazz
+  # A vertex labeled directed tree with the following recursive internal
+  # structure:
+  #
+  # {
+  #   input_name: String,
+  #   output_name: String,
+  #   children: [
+  #     TranslationNode
+  #   ]
+  # }
+  class TranslationNode
+    extend Forwardable
+
+    attr_reader :input_name, :output_name, :children
+
+    def initialize(input_name:, output_name:, children: [])
+      @input_name = input_name
+      @output_name = output_name
+      @children = children
+    end
+
+    def_delegators :@children, :each, :map, :first
+  end
+end

data/lib/szamlazz/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Szamlazz
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: szamlazz
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Simonyi Gergő
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-04-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: builder
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/inflections.rb
+- lib/pdf_validator.rb
+- lib/szamlazz.rb
+- lib/szamlazz/create_invoice.rb
+- lib/szamlazz/create_invoice/default_options.rb
+- lib/szamlazz/create_invoice/key_translations.rb
+- lib/szamlazz/szamlazz_error.rb
+- lib/szamlazz/translation_node.rb
+- lib/szamlazz/version.rb
+homepage: 
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Ruby wrapper for Számlázz.hu's Számla Agent.
+test_files: []