dtaus 0.1.1 → 0.2.0

data/README.markdown

@@ -1,8 +1,8 @@
 DTAUS
 =====
 
-This is a library specific to the german banking sector. Therefore the documentation will be in german. If you have any questions please feel free to email me at mikezter@gmail.com
-
+This is a library specific to the german banking sector. Therefore the documentation will be in german. If you have any questions please feel free to email me at mikezter@gmail.com
+
 Beim Datenträgeraustausch (DTA) werden Zahlungsverkehrsdaten - also Überweisungen und Lastschriften - als Datei an ein Geldinstitut übergeben. Dieser Gem stellt Klassen bereit solche Dateien zu erzeugen.
 
 Download
@@ -16,46 +16,63 @@ Usage
 Ablauf:
 
 * Erstelle ein Auftraggeber-Konto 
-* Erstelle ein DTAUS Objekt für diesen Auftraggeber
+* Erstelle ein Datensatz für diesen Auftraggeber
 * Erstelle ein oder mehrerere Kunden-Konten mit dazugehörigen Buchungen
-* Füge die Buchungen dem DTAUS Objekt hinzu
-* Schreibe eine DTAUS Datei
-* _Alternativ:_ Gebe die Daten als String aus
+* Füge die Buchungen dem Datensatz hinzu
+* Schreibe den Datensatz als DTAUS Datei
+* _Alternativ:_ Gib die Daten als String aus
 
 In Ruby:
  
-    auftraggeber = DTAUS::Konto.new(1234567890, 12345670, 'Muster GmbH', 'Deutsche Bank', true)
-
-    dta = DTAUS.new(auftraggeber)
-
-    kunde = DTAUS::Konto.new(1234567890, 12345670, 'Max Meier-Schulze', 'Sparkasse')
-    buchung = DTAUS::Buchung.new(auftraggeber, kunde, 39.99, 'Vielen Dank für ihren Einkauf vom 01.01.2010. Rechnungsnummer 12345')
-
-    dta.add(buchung)
-
-    dta.to_file
-
-    puts dta
-
+``` ruby
+require 'dtaus'
+
+# Konto des Auftraggebers
+konto_auftraggeber = DTAUS::Konto.new(
+  :kontonummer => 1234567890, 
+  :blz => 82070024, 
+  :kontoinhaber => 'inoxio Quality Services GmbH', 
+  :bankname =>'Deutsche Bank',
+  :is_auftraggeber => true
+)
+
+# LASTSCHRIFT
+# Erstellen eines Datensatzes für eine Lastschrift
+lastschrift = DTAUS::Datensatz.new(:lastschrift, konto_auftraggeber)
+
+# Konto des Kunden
+konto_kunde = DTAUS::Konto.new(
+  :kontonummer => 1234567890, 
+  :blz => 12030000, 
+  :kontoinhaber => 'Max Meier-Schulze', 
+  :bankname =>'Sparkasse',
+  :kundennummer => 77777777777
+)
+# Lastschrift-Buchung für den Kunden
+buchung = DTAUS::Buchung.new(
+  :kunden_konto => konto_kunde,
+  :betrag => "9,99",
+  :transaktionstyp => :lastschrift,
+  :verwendungszweck => "Vielen Dank für Ihren Einkauf!"
+)
+lastschrift.add(buchung)
+
+lastschrift.to_file
+puts lastschrift
+```
+
+Siehe: [example/example.rb](https://github.com/alphaone/dtaus/blob/master/example/example.rb)
  
 Einschränkungen:
 ----------------
 
-* Es sind nur Lastschriften möglich. __Typ der Datei ist LK__ (Lastschrift Kunde).
+* Es sind nur Lastschriften und Gutschriften möglich. __Typ der Datei ist LK oder GK__ (Lastschrift-Kunde oder Gutschrift-Kunde).
 * Auftraggeber, Empfänger und Verwendungszweck können jeweils 27 Zeichen enthalten. Es stehen 15 Erweiterungen à 27 Zeichen zur Verfügung. Jede Erweiterung kann entweder Auftraggeber, Empfänger oder Verwendungszweck erweitern.
 
-Todo:
-------
-
-* Gutschriften ermöglichen
-* Refactor to Module instead of Class with Subclasses
-* Parameter als Hash annehmen (vor allem für `Konto` und `Buchung`)
-* weiteres?
-
 Weitere Informationen
 ---------------------
-
+
 Infos zu DTAUS: http://www.infodrom.org/projects/dtaus/dtaus.html
-
+
 DTAUS online check: http://www.xpecto.de/index.php?id=148,7
 

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => [:test]
+
+desc 'Test the dtaus gem.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'dtaus'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the dtaus gem.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'DTAUS'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.options << '--charset' << 'utf-8'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/example/example.rb

@@ -0,0 +1,63 @@
+ROOT = File.join(File.dirname(__FILE__), '..')
+$LOAD_PATH << File.join(ROOT, 'lib')
+$LOAD_PATH << File.join(ROOT, 'lib', 'dtaus')
+
+require 'dtaus'
+
+# Konto des Auftraggebers
+konto_auftraggeber = DTAUS::Konto.new(
+  :kontonummer => 1234567890, 
+  :blz => 82070024, 
+  :kontoinhaber => 'inoxio Quality Services GmbH', 
+  :bankname =>'Deutsche Bank',
+  :is_auftraggeber => true
+)
+
+# GUTSCHRIFT
+# Erstellen eines Datensatzes für eine Gutschrift
+gutschrift = DTAUS::Datensatz.new(:gutschrift, konto_auftraggeber)
+
+# Konto des Kunden
+konto_kunde = DTAUS::Konto.new(
+  :kontonummer => 1234567890, 
+  :blz => 12030000, 
+  :kontoinhaber => 'Max Meier-Schulze', 
+  :bankname =>'Sparkasse',
+  :kundennummer => 77777777777
+)
+# Gutschrift-Buchung für den Kunden
+buchung = DTAUS::Buchung.new(
+  :kunden_konto => konto_kunde,
+  :betrag => "9,99",
+  :transaktionstyp => :gutschrift,
+  :verwendungszweck => "Vielen Dank für Ihren Einkauf!"
+)
+gutschrift.add(buchung)
+
+gutschrift.to_file('gutschrift.txt')
+puts gutschrift
+
+# LASTSCHRIFT
+# Erstellen eines Datensatzes für eine Lastschrift
+lastschrift = DTAUS::Datensatz.new(:lastschrift, konto_auftraggeber)
+
+# Konto des Kunden
+konto_kunde = DTAUS::Konto.new(
+  :kontonummer => 1234567890, 
+  :blz => 12030000, 
+  :kontoinhaber => 'Max Meier-Schulze', 
+  :bankname =>'Sparkasse',
+  :kundennummer => 77777777777
+)
+# Lastschrift-Buchung für den Kunden
+buchung = DTAUS::Buchung.new(
+  :kunden_konto => konto_kunde,
+  :betrag => "9,99",
+  :transaktionstyp => :lastschrift,
+  :verwendungszweck => "Vielen Dank für Ihren Einkauf!"
+)
+lastschrift.add(buchung)
+
+lastschrift.to_file('lastschrift.txt')
+puts lastschrift
+

data/lib/dtaus/buchung.rb

@@ -1,116 +1,82 @@
-require 'enumerator'
-require 'dtaus/erweiterung'
+# encoding: utf-8
 
-class DTAUS
+module DTAUS
 
-  # Buchung erstellen
-  #  buchung = Buchung.new(auftraggeber_konto, kunden_konto, betrag, verwendungszweck)
-  #
-  # auftraggeber_konto und kunden_konto müssen ein DTAUS::Konto sein
-  # betrag muss ein Float sein
-  #
+  # Buchungsdaten mit zwei Konten (Auftraggeber und Kunde),
+  # Betrag und Verwendungszweck
   class Buchung
-    attr_reader :betrag, :konto, :text, :positiv, :auftraggeber
-    alias :positiv? :positiv
 
-    def initialize(_auftraggeber, _konto, _betrag, _text = "")
-      raise DTAusException.new("Konto expected, got #{_konto.class}") unless _konto.is_a?(Konto)
-      raise DTAUSException.new("Betrag is a #{_betrag.class}, expected Float") unless _betrag.is_a?(Float)
-      raise DTAUSException.new("Betrag ist 0.0") unless _betrag > 0
+    attr_reader :betrag, :kunden_konto, :auftraggeber_konto, :verwendungszweck, :positiv, :transaktionstyp
+    alias :positiv? :positiv
 
-      @auftraggeber = _auftraggeber
-      @konto        = _konto
-      @text         = DTAUS.convert_text(_text)
+    # Buchung erstellen
+    #
+    # +params+ as Hash:
+    # [<tt>:kunden_konto</tt>] DTAUS::Konto des Kunden
+    # [<tt>:betrag</tt>] der Betrag der Buchung in +Float+
+    # [<tt>:transaktionstyp</tt>] Art der Transaktion
+    #                             * <tt>:lastschrift</tt> Lastschrift des Einzugsermächtigungsverfahren
+    #                             * <tt>:gutschrift</tt> Überweisungs-Gutschrift
+    #                             _optional_, Default-Wert ist <tt>:lastschrift</tt>
+    # [<tt>:verwendungszweck</tt>] der Verwendungszweck der Buchung; _optional_, Default-Wert ist ""
+    def initialize(params = {})
+      # defaults
+      params = {
+        :transaktionstyp => :lastschrift,
+        :verwendungszweck => ''
+      }.merge(params)
+
+      [:betrag, :kunden_konto].each do |attr|
+        raise ArgumentError.new("Missing params[:#{attr}] for new Buchung.") if params[attr].nil?
+      end
 
-      raise IncorrectSize.new("Zuviele Erweiterungen: #{erweiterungen.size}, maximal 15. Verwendungszweck zu lang?") if erweiterungen.size > 15
+      unless params[:kunden_konto].is_a?(Konto)
+        raise DTAUSException.new("Konto expected for Parameter 'kunden_konto', got #{params[:kunden_konto].class}")
+      end
+      unless [:lastschrift, :gutschrift].include?(params[:transaktionstyp])
+        raise DTAUSException.new("Transaktionstyp has to be one of [:lastschrift, :gutschrift]")
+      end
 
-      @betrag = (_betrag * 100).round.to_i  # Euro-Cent
-      if betrag > 0
-        @positiv  = true
+      # betrag to BigDecimal
+      if params[:betrag].is_a? String
+        params[:betrag] = BigDecimal.new params[:betrag].sub(',', '.')
+      elsif params[:betrag].is_a? Numeric
+        params[:betrag] = BigDecimal.new params[:betrag].to_s
       else
-        @betrag   = -betrag # only store positive amounts
-        @positiv  = false
+        raise DTAUSException.new("Betrag is a #{params[:betrag].class}, expected String or Numeric")
       end
-    end
-
-
-    # 5 Zeichen  Art der Transaktion (7a: 2 Zeichen, 7b: 3 Zeichen)
-    # "04000" Lastschrift des Abbuchungsauftragsverfahren
-    # "05000" Lastschrift des Einzugsermächtigungsverfahren
-    # "05005" Lastschrift aus Verfügung im elektronischen Cash-System
-    # "05006" Wie 05005 mit ausländischen Karten
-    # "05015" Lastschrift aus Verfügung im elec. Cash-System - POZ
-    # "51000" Überweisungs-Gutschrift
-    # "53000" Überweisung Lohn/Gehalt/Rente
-    # "54XXJ" Vermögenswirksame Leistung (VL) mit Sparzulage
-    # "56000" Überweisung öffentlicher Kassen
-    # Die im Textschlüssel mit XX bezeichnete Stelle ist 00 oder der Prozentsatz der Sparzulage.
-    # Die im Textschlüssel mit J bezeichnete Stelle wird bei Übernahme in eine Zahlung automatisch mit der jeweils aktuellen Jahresendziffer (z.B. 7, wenn 97) ersetzt.
-    #
-    def zahlungsart
-      '05000'
-    end
-
-    def verwendungszweck_erweiterungen
-      Erweiterung.from_string(:verwendungszweck, text)
-    end
-
-    def erweiterungen
-      @erweiterungen ||= konto.erweiterungen + auftraggeber.erweiterungen + verwendungszweck_erweiterungen
-    end
-
-    def to_dta
-      "#{dataC}#{dataC_erweiterungen}"
-    end
 
-    def size
-      (187 + erweiterungen.size * 29)
-    end
+      # Betrag in Cent
+      params[:betrag] = ( params[:betrag] * 100 ).to_i
+      if params[:betrag] == 0
+        raise DTAUSException.new("Betrag must not be 0.00 €!")
+      elsif params[:betrag] > 0
+        @betrag  = params[:betrag]
+        @positiv = true
+      else
+        @betrag  = params[:betrag] * -1
+        @positiv = false
+      end
 
-  private
+      @kunden_konto       = params[:kunden_konto]
+      @transaktionstyp    = params[:transaktionstyp]
+      @verwendungszweck   = Converter.convert_text(params[:verwendungszweck])
 
-    # Erstellt den Erweiterungen-Teil des C-Segments für diese Buchung
-    #
-    def dataC_erweiterungen
-      dta = auftraggeber.name[0..26].ljust(27) # 27 Zeichen  Name des Auftraggebers
-      dta += text[0..26].ljust(27)             # 27 Zeichen  Verwendungszweck
-      dta += '1'                               # 1 Zeichen  Währungskennzeichen ('1' = Euro)
-      dta += '  '                              # 2 Zeichen   Reserviert, 2 Blanks
-      dta += "%02i" % erweiterungen.size       # 2 Zeichen   Anzahl der Erweiterungsdatensätze, "00" bis "15"
-      dta += erweiterungen[0..1].inject('') {|data, erweiterung| data += erweiterung.to_dta}
-      dta = dta.ljust(128)
-      if erweiterungen.size > 2
-        erweiterungen[2..-1].each_slice(4) do |slice|
-          dta += slice.inject('') {|dta, erweiterung| dta += erweiterung.to_dta}.ljust(128)
-        end
+      if erweiterungen.size > 15
+        raise IncorrectSizeException.new("Zuviele Erweiterungen: #{erweiterungen.size}, maximal 15. Verwendungszweck zu lang?")
       end
-      raise IncorrectSize.new("Erweiterungen: #{dta.size} Zeichen") if dta.size > 256 * 3 or dta.size % 128 != 0
-      return dta
 
     end
 
-    # Erstellt ein C-Segments für diese Buchung
+    # Alle Erweiterungen der Buchung, bestehend aus
+    # * Inhaber Kundenkonto
+    # * Verwendungszweck dieser Buchung
     #
-    def dataC
-      dta  = '%04i' % size                         #  4 Zeichen  Länge des Datensatzes, 187 + x * 29 (x..Anzahl Erweiterungsteile)
-      dta += 'C'                                   #  1 Zeichen  Datensatz-Typ, immer 'C'
-      dta += '%08i' % 0                            #  8 Zeichen  Bankleitzahl des Auftraggebers (optional)
-      dta += '%08i' % konto.blz                    #  8 Zeichen  Bankleitzahl des Kunden
-      dta += '%010i' % konto.nummer                # 10 Zeichen  Kontonummer des Kunden
-      dta += '0%011i0' % konto.kunnr               # 13 Zeichen  Verschiedenes 1. Zeichen: "0" 2. - 12. Zeichen: interne Kundennummer oder Nullen 13. Zeichen: "0"
-      dta += zahlungsart                           #  5 Zeichen  Art der Transaktion (7a: 2 Zeichen, 7b: 3 Zeichen)
-      dta += ' '                                   #  1 Zeichen  Reserviert, " " (Blank)
-      dta += '0' * 11                              # 11 Zeichen  Betrag
-      dta += '%08i' % auftraggeber.blz             #  8 Zeichen  Bankleitzahl des Auftraggebers
-      dta += '%010i' % auftraggeber.nummer         # 10 Zeichen  Kontonummer des Auftraggebers
-      dta += '%011i' % betrag                      # 11 Zeichen  Betrag in Euro einschließlich Nachkommastellen, nur belegt, wenn Euro als Währung angegeben wurde
-      dta += ' ' * 3                               #  3 Zeichen  Reserviert, 3 Blanks
-      dta += konto.name[0..26].ljust(27)           # 27 Zeichen  Name des Kunden
-      dta +=  ' ' * 8                              #  8 Zeichen  Reserviert, 8 Blanks
-      raise IncorrectSize.new("C-Segement 1: #{dta.size} Zeichen, 128 erwartet (#{konto.name})") if dta.size != 128
-      return dta
+    # Die Erweiterung für das auftraggeber_konto werden hier nicht aufgeführt!
+    def erweiterungen
+      kunden_konto.erweiterungen +
+      Erweiterung.from_string(:verwendungszweck, verwendungszweck)
     end
 
   end
 end
-

data/lib/dtaus/converter.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+
+module DTAUS
+  
+  # Utility class for converting strings and numbers to DTA-conform representations
+  class Converter
+    
+    # Zeichen umsetzen gemäss DTA-Norm
+    #
+    def self.convert_text(_text)
+      tmp = _text.to_s.dup
+      tmp = tmp.upcase()
+      tmp = tmp.gsub('Ä', 'AE')
+      tmp = tmp.gsub('Ü', 'UE')
+      tmp = tmp.gsub('Ö', 'OE')
+      tmp = tmp.gsub('ä', 'AE')
+      tmp = tmp.gsub('ü', 'UE')
+      tmp = tmp.gsub('ö', 'OE')
+      tmp = tmp.gsub('ß', 'SS')
+      tmp = tmp.strip
+    end
+
+    # Konvertiert einen String in einen Integer
+    # indem alle Nicht-Digits entfernt werden.
+    # Lässt Integer unberührt.
+    #
+    def self.convert_number(_number)
+      case _number
+        when Integer then _number
+        when String then _number.strip.gsub(/\D/, '').to_i
+        else raise DTAUSException.new("Cannot convert #{_number.class} to Integer")
+      end
+    end
+    
+  end
+end

data/lib/dtaus/datensatz.rb

@@ -0,0 +1,77 @@
+# encoding: utf-8
+
+module DTAUS
+  
+  # Vollständiger DTA-Datensatz mit Header (A), Body (C) und Footer (E)
+  class Datensatz
+
+    attr_reader :auftraggeber_konto, :buchungen, :ausfuehrungsdatum, :positiv, :transaktionstyp
+    alias :positiv? :positiv
+
+    # Vollständigen DTA-Datensatz erstellen
+    #
+    # Parameter:
+    # [<tt>_transaktionstyp</tt>] Art der Transaktionen (als :Symbol)
+    #                             * <tt>:lastschrift</tt> für Lastschriften Kundenseitig
+    #                             * <tt>:gutschrift</tt> für Gutschriften Kundenseitig
+    # [<tt>_auftraggeber_konto</tt>] das DTAUS::Konto des Auftraggebers
+    # [<tt>_ausfuehrungsdatum</tt>] Ausführungsdatum des Datensatzes,
+    #                               _optional_, Default-Wert ist die aktuelle Zeit
+    #
+    def initialize(_transaktionstyp, _auftraggeber_konto, _ausfuehrungsdatum = Time.now)
+      unless [:lastschrift, :gutschrift].include?(_transaktionstyp)
+        raise DTAUSException.new("Transaktionstyp has to be one of [:lastschrift, :gutschrift]") 
+      end
+      unless _auftraggeber_konto.is_a?(Konto)
+        raise DTAUSException.new("Konto expected, got #{_auftraggeber_konto.class}") 
+      end
+      unless _ausfuehrungsdatum.is_a?(Date) or _ausfuehrungsdatum.is_a?(Time)
+        raise DTAUSException.new("Date or Time expected, got #{_ausfuehrungsdatum.class}") 
+      end
+
+      @transaktionstyp    = _transaktionstyp
+      @auftraggeber_konto = _auftraggeber_konto
+      @ausfuehrungsdatum  = _ausfuehrungsdatum
+      @buchungen          = []
+    end
+
+    # Eine Buchung zum Datensatz hinzufügen.
+    #
+    # Es wird geprüft, ob das Vorzeichen identisch mit den bisherigen Vorzeichen ist.
+    #
+    def add(_buchung)
+      raise DTAUSException.new("Buchung expected, got #{_buchung.class}") unless _buchung.is_a?(Buchung)
+      
+      # Die erste Buchung bestimmt, ob alle Beträge positiv oder negativ sind.
+      @positiv = _buchung.positiv? if @buchungen.empty?
+      
+      # Wirf Exception wenn Vorzeichen gemischt werden
+      unless @positiv == _buchung.positiv?
+        raise DTAUSException.new("Nicht erlaubter Vorzeichenwechsel! "+
+                                 "Buchung muss wie die vorherigen Buchungen #{positiv? ? 'positiv' : 'negativ'} sein!")
+      end
+      
+      @buchungen << _buchung
+    end
+
+    # DTA-Repräsentation dieses Datensatzes
+    #
+    def to_dta
+      DtaGenerator.new(self).to_dta
+    end
+    alias :to_s :to_dta
+
+    # Schreibt die DTAUS-Datei
+    #
+    # Parameter:
+    # [<tt>filename</tt>] Name der zu schreibenden Datei; _optional_, Default-Wert ist <tt>DTAUS0.TXT</tt>
+    #
+    def to_file(filename = 'DTAUS0.TXT')
+      File.open(filename, 'w') do |file|
+        file << to_dta
+      end
+    end
+
+  end
+  
+end