SL/DB/Helper/Payment.pm

   1 package SL::DB::Helper::Payment;
   2
   3 use strict;
   4
   5 use parent qw(Exporter);
   6 our @EXPORT = qw(pay_invoice);
   7 our @EXPORT_OK = qw(skonto_date skonto_charts amount_less_skonto within_skonto_period percent_skonto reference_account reference_amount open_amount open_percent remaining_skonto_days skonto_amount check_skonto_configuration valid_skonto_amount get_payment_suggestions validate_payment_type open_sepa_transfer_amount get_payment_select_options_for_bank_transaction exchangerate forex);
   8 our %EXPORT_TAGS = (
   9   "ALL" => [@EXPORT, @EXPORT_OK],
  10 );
  11
  12 require SL::DB::Chart;
  13 use Data::Dumper;
  14 use DateTime;
  15 use SL::DATEV qw(:CONSTANTS);
  16 use SL::Locale::String qw(t8);
  17 use List::Util qw(sum);
  18 use SL::DB::Exchangerate;
  19 use SL::DB::Currency;
  20 use Carp;
  21
  22 #
  23 # Public functions not exported by default
  24 #
  25
  26 sub pay_invoice {
  27   my ($self, %params) = @_;
  28
  29   require SL::DB::Tax;
  30
  31   my $is_sales = ref($self) eq 'SL::DB::Invoice';
  32   my $mult = $is_sales ? 1 : -1;  # multiplier for getting the right sign depending on ar/ap
  33   my @new_acc_ids;
  34   my $paid_amount = 0; # the amount that will be later added to $self->paid, should be in default currency
  35
  36   # default values if not set
  37   $params{payment_type} = 'without_skonto' unless $params{payment_type};
  38   validate_payment_type($params{payment_type});
  39
  40   # check for required parameters
  41   Common::check_params(\%params, qw(chart_id transdate));
  42
  43   my $transdate_obj;
  44   if (ref($params{transdate} eq 'DateTime')) {
  45     $transdate_obj = $params{transdate};
  46   } else {
  47    $transdate_obj = $::locale->parse_date_to_object($params{transdate});
  48   };
  49   croak t8('Illegal date') unless ref $transdate_obj;
  50
  51   # check for closed period
  52   my $closedto = $::locale->parse_date_to_object($::instance_conf->get_closedto);
  53   if ( ref $closedto && $transdate_obj < $closedto ) {
  54     croak t8('Cannot post payment for a closed period!');
  55   };
  56
  57   # check for maximum number of future days
  58   if ( $::instance_conf->get_max_future_booking_interval > 0 ) {
  59     croak t8('Cannot post transaction above the maximum future booking date!') if $transdate_obj > DateTime->now->add( days => $::instance_conf->get_max_future_booking_interval );
  60   };
  61
  62   # currency is either passed or use the invoice currency if it differs from the default currency
  63   my ($exchangerate,$currency);
  64   if ($params{currency} || $params{currency_id} || $self->currency_id != $::instance_conf->get_currency_id) {
  65     if ($params{currency} || $params{currency_id} ) { # currency was specified
  66       $currency = SL::DB::Manager::Currency->find_by(name => $params{currency}) || SL::DB::Manager::Currency->find_by(id => $params{currency_id});
  67     } else { # use invoice currency
  68       $currency = SL::DB::Manager::Currency->find_by(id => $self->currency_id);
  69     };
  70     die "no currency" unless $currency;
  71     if ($currency->id == $::instance_conf->get_currency_id) {
  72       $exchangerate = 1;
  73     } else {
  74       my $rate = SL::DB::Manager::Exchangerate->find_by(currency_id => $currency->id,
  75                                                         transdate   => $transdate_obj,
  76                                                        );
  77       if ($rate) {
  78         $exchangerate = $is_sales ? $rate->buy : $rate->sell;
  79       } else {
  80         die "No exchange rate for " . $transdate_obj->to_kivitendo;
  81       };
  82     };
  83   } else { # no currency param given or currency is the same as default_currency
  84     $exchangerate = 1;
  85   };
  86
  87   # input checks:
  88   if ( $params{'payment_type'} eq 'without_skonto' ) {
  89     croak "invalid amount for payment_type 'without_skonto': $params{'amount'}\n" unless abs($params{'amount'}) > 0;
  90   };
  91
  92   # options with_skonto_pt and difference_as_skonto don't require the parameter
  93   # amount, but if amount is passed, make sure it matches the expected value
  94   if ( $params{'payment_type'} eq 'difference_as_skonto' ) {
  95     croak "amount $params{amount} doesn't match open amount " . $self->open_amount . ", diff = " . ($params{amount}-$self->open_amount) if $params{amount} && abs($self->open_amount - $params{amount} ) > 0.0000001;
  96   } elsif ( $params{'payment_type'} eq 'with_skonto_pt' ) {
  97     croak "amount $params{amount} doesn't match amount less skonto: " . $self->amount_less_skonto . "\n" if $params{amount} && abs($self->amount_less_skonto - $params{amount} ) > 0.0000001;
  98     croak "payment type with_skonto_pt can't be used if payments have already been made" if $self->paid != 0;
  99   };
 100
 101   # absolute skonto amount for invoice, use as reference sum to see if the
 102   # calculated skontos add up
 103   # only needed for payment_term "with_skonto_pt"
 104
 105   my $skonto_amount_check = $self->skonto_amount; # variable should be zero after calculating all skonto
 106   my $total_open_amount   = $self->open_amount;
 107
 108   # account where money is paid to/from: bank account or cash
 109   my $account_bank = SL::DB::Manager::Chart->find_by(id => $params{chart_id});
 110   croak "can't find bank account with id " . $params{chart_id} unless ref $account_bank;
 111
 112   my $reference_account = $self->reference_account;
 113   croak "can't find reference account (link = AR/AP) for invoice" unless ref $reference_account;
 114
 115   my $memo   = $params{memo}   // '';
 116   my $source = $params{source} // '';
 117
 118   my $rounded_params_amount = _round( $params{amount} ); # / $exchangerate);
 119   my $fx_gain_loss_amount = 0; # for fx_gain and fx_loss
 120
 121   my $db = $self->db;
 122   $db->with_transaction(sub {
 123     my $new_acc_trans;
 124
 125     # all three payment type create 1 AR/AP booking (the paid part)
 126     # difference_as_skonto creates n skonto bookings (1 for each tax type)
 127     # with_skonto_pt creates 1 bank booking and n skonto bookings (1 for each tax type)
 128     # without_skonto creates 1 bank booking
 129
 130     # as long as there is no automatic tax, payments are always booked with
 131     # taxkey 0
 132
 133     unless ( $params{payment_type} eq 'difference_as_skonto' ) {
 134       # cases with_skonto_pt and without_skonto
 135
 136       # for case with_skonto_pt we need to know the corrected amount at this
 137       # stage if we are going to use $params{amount}
 138
 139       my $pay_amount = $rounded_params_amount;
 140       $pay_amount = $self->amount_less_skonto if $params{payment_type} eq 'with_skonto_pt';
 141
 142       # bank account and AR/AP
 143       $paid_amount += $pay_amount * $exchangerate;
 144
 145       my $amount = (-1 * $pay_amount) * $mult;
 146
 147
 148       # total amount against bank, do we already know this by now?
 149       $new_acc_trans = SL::DB::AccTransaction->new(trans_id   => $self->id,
 150                                                    chart_id   => $account_bank->id,
 151                                                    chart_link => $account_bank->link,
 152                                                    amount     => $amount,
 153                                                    transdate  => $transdate_obj,
 154                                                    source     => $source,
 155                                                    memo       => $memo,
 156                                                    project_id => $params{project_id} ? $params{project_id} : undef,
 157                                                    taxkey     => 0,
 158                                                    tax_id     => SL::DB::Manager::Tax->find_by(taxkey => 0)->id);
 159       $new_acc_trans->save;
 160
 161       push @new_acc_ids, $new_acc_trans->acc_trans_id;
 162       # deal with fxtransaction
 163       if ( $self->currency_id != $::instance_conf->get_currency_id ) {
 164         my $fxamount = _round($amount - ($amount * $exchangerate));
 165         $new_acc_trans = SL::DB::AccTransaction->new(trans_id       => $self->id,
 166                                                      chart_id       => $account_bank->id,
 167                                                      chart_link     => $account_bank->link,
 168                                                      amount         => $fxamount * -1,
 169                                                      transdate      => $transdate_obj,
 170                                                      source         => $source,
 171                                                      memo           => $memo,
 172                                                      taxkey         => 0,
 173                                                      fx_transaction => 1,
 174                                                      tax_id         => SL::DB::Manager::Tax->find_by(taxkey => 0)->id);
 175         $new_acc_trans->save;
 176         push @new_acc_ids, $new_acc_trans->acc_trans_id;
 177         # if invoice exchangerate differs from exchangerate of payment
 178         # deal with fxloss and fxamount
 179         if ($self->exchangerate and $self->exchangerate != 1 and $self->exchangerate != $exchangerate) {
 180           my $fxgain_chart = SL::DB::Manager::Chart->find_by(id => $::instance_conf->get_fxgain_accno_id) || die "Can't determine fxgain chart";
 181           my $fxloss_chart = SL::DB::Manager::Chart->find_by(id => $::instance_conf->get_fxloss_accno_id) || die "Can't determine fxloss chart";
 182           my $gain_loss_amount = _round($amount * ($exchangerate - $self->exchangerate ) * -1,2);
 183           my $gain_loss_chart = $gain_loss_amount > 0 ? $fxgain_chart : $fxloss_chart;
 184           $fx_gain_loss_amount = $gain_loss_amount;
 185
 186           $new_acc_trans = SL::DB::AccTransaction->new(trans_id       => $self->id,
 187                                                        chart_id       => $gain_loss_chart->id,
 188                                                        chart_link     => $gain_loss_chart->link,
 189                                                        amount         => $gain_loss_amount,
 190                                                        transdate      => $transdate_obj,
 191                                                        source         => $source,
 192                                                        memo           => $memo,
 193                                                        taxkey         => 0,
 194                                                        fx_transaction => 0,
 195                                                        tax_id         => SL::DB::Manager::Tax->find_by(taxkey => 0)->id);
 196           $new_acc_trans->save;
 197           push @new_acc_ids, $new_acc_trans->acc_trans_id;
 198
 199         };
 200       };
 201     };
 202
 203     if ( $params{payment_type} eq 'difference_as_skonto' or $params{payment_type} eq 'with_skonto_pt' ) {
 204
 205       my $total_skonto_amount;
 206       if ( $params{payment_type} eq 'with_skonto_pt' ) {
 207         $total_skonto_amount = $self->skonto_amount;
 208       } elsif ( $params{payment_type} eq 'difference_as_skonto' ) {
 209         $total_skonto_amount = $self->open_amount;
 210       };
 211
 212       my @skonto_bookings = $self->skonto_charts($total_skonto_amount);
 213
 214       # error checking:
 215       if ( $params{payment_type} eq 'difference_as_skonto' ) {
 216         my $calculated_skonto_sum  = sum map { $_->{skonto_amount} } @skonto_bookings;
 217         croak "calculated skonto for difference_as_skonto = $calculated_skonto_sum doesn't add up open amount: " . $self->open_amount unless _round($calculated_skonto_sum) == _round($self->open_amount);
 218       };
 219
 220       my $reference_amount = $total_skonto_amount;
 221
 222       # create an acc_trans entry for each result of $self->skonto_charts
 223       foreach my $skonto_booking ( @skonto_bookings ) {
 224         next unless $skonto_booking->{'chart_id'};
 225         next unless $skonto_booking->{'skonto_amount'} != 0;
 226         my $amount = -1 * $skonto_booking->{skonto_amount};
 227         $new_acc_trans = SL::DB::AccTransaction->new(trans_id   => $self->id,
 228                                                      chart_id   => $skonto_booking->{'chart_id'},
 229                                                      chart_link => SL::DB::Manager::Chart->find_by(id => $skonto_booking->{'chart_id'})->link,
 230                                                      amount     => $amount * $mult,
 231                                                      transdate  => $transdate_obj,
 232                                                      source     => $params{source},
 233                                                      taxkey     => 0,
 234                                                      tax_id     => SL::DB::Manager::Tax->find_by(taxkey => 0)->id);
 235
 236         # the acc_trans entries are saved individually, not added to $self and then saved all at once
 237         $new_acc_trans->save;
 238         push @new_acc_ids, $new_acc_trans->acc_trans_id;
 239
 240         $reference_amount -= abs($amount);
 241         $paid_amount      += -1 * $amount * $exchangerate;
 242         $skonto_amount_check -= $skonto_booking->{'skonto_amount'};
 243       };
 244       if ( $params{payment_type} eq 'difference_as_skonto' ) {
 245           die "difference_as_skonto calculated incorrectly, sum of calculated payments doesn't add up to open amount $total_open_amount, reference_amount = $reference_amount\n" unless _round($reference_amount) == 0;
 246       }
 247
 248     };
 249
 250     my $arap_amount = 0;
 251
 252     if ( $params{payment_type} eq 'difference_as_skonto' ) {
 253       $arap_amount = $total_open_amount;
 254     } elsif ( $params{payment_type} eq 'without_skonto' ) {
 255       $arap_amount = $rounded_params_amount;
 256     } elsif ( $params{payment_type} eq 'with_skonto_pt' ) {
 257       # this should be amount + sum(amount+skonto), but while we only allow
 258       # with_skonto_pt for completely unpaid invoices we just use the value
 259       # from the invoice
 260       $arap_amount = $total_open_amount;
 261     };
 262
 263     # regardless of payment_type there is always only exactly one arap booking
 264     # TODO: compare $arap_amount to running total
 265     my $arap_booking= SL::DB::AccTransaction->new(trans_id   => $self->id,
 266                                                   chart_id   => $reference_account->id,
 267                                                   chart_link => $reference_account->link,
 268                                                   amount     => _round($arap_amount * $mult * $exchangerate - $fx_gain_loss_amount),
 269                                                   transdate  => $transdate_obj,
 270                                                   source     => '', #$params{source},
 271                                                   taxkey     => 0,
 272                                                   tax_id     => SL::DB::Manager::Tax->find_by(taxkey => 0)->id);
 273     $arap_booking->save;
 274     push @new_acc_ids, $arap_booking->acc_trans_id;
 275
 276     $fx_gain_loss_amount *= -1 if $self->is_sales;
 277     $self->paid($self->paid + _round($paid_amount) + $fx_gain_loss_amount) if $paid_amount;
 278     $self->datepaid($transdate_obj);
 279     $self->save;
 280
 281     # make sure transactions will be reloaded the next time $self->transactions
 282     # is called, as pay_invoice saves the acc_trans objects individually rather
 283     # than adding them to the transaction relation array.
 284     $self->forget_related('transactions');
 285
 286     my $datev_check = 0;
 287     if ( $is_sales )  {
 288       if ( (  $self->invoice && $::instance_conf->get_datev_check_on_sales_invoice  ) ||
 289            ( !$self->invoice && $::instance_conf->get_datev_check_on_ar_transaction )) {
 290         $datev_check = 1;
 291       }
 292     } else {
 293       if ( (  $self->invoice && $::instance_conf->get_datev_check_on_purchase_invoice ) ||
 294            ( !$self->invoice && $::instance_conf->get_datev_check_on_ap_transaction   )) {
 295         $datev_check = 1;
 296       }
 297     }
 298
 299     if ( $datev_check ) {
 300
 301       my $datev = SL::DATEV->new(
 302         dbh        => $db->dbh,
 303         trans_id   => $self->{id},
 304       );
 305
 306       $datev->generate_datev_data;
 307
 308       if ($datev->errors) {
 309         # this exception should be caught by with_transaction, which handles the rollback
 310         die join "\n", $::locale->text('DATEV check returned errors:'), $datev->errors;
 311       }
 312     }
 313
 314     1;
 315
 316   }) || die t8('error while paying invoice #1 : ', $self->invnumber) . $db->error . "\n";
 317   return wantarray ? @new_acc_ids : 1;
 318 }
 319
 320 sub skonto_date {
 321
 322   my $self = shift;
 323
 324   my $is_sales = ref($self) eq 'SL::DB::Invoice';
 325
 326   my $skonto_date;
 327
 328   if ( $is_sales ) {
 329     return undef unless ref $self->payment_terms;
 330     return undef unless $self->payment_terms->terms_skonto > 0;
 331     $skonto_date = DateTime->from_object(object => $self->transdate)->add(days => $self->payment_terms->terms_skonto);
 332   } else {
 333     return undef unless ref $self->vendor->payment_terms;
 334     return undef unless $self->vendor->payment_terms->terms_skonto > 0;
 335     $skonto_date = DateTime->from_object(object => $self->transdate)->add(days => $self->vendor->payment_terms->terms_skonto);
 336   };
 337
 338   return $skonto_date;
 339 };
 340
 341 sub reference_account {
 342   my $self = shift;
 343
 344   my $is_sales = ref($self) eq 'SL::DB::Invoice';
 345
 346   require SL::DB::Manager::AccTransaction;
 347
 348   my $link_filter = $is_sales ? 'AR' : 'AP';
 349
 350   my $acc_trans = SL::DB::Manager::AccTransaction->find_by(
 351      trans_id   => $self->id,
 352      SL::DB::Manager::AccTransaction->chart_link_filter("$link_filter")
 353   );
 354
 355   return undef unless ref $acc_trans;
 356
 357   my $reference_account = SL::DB::Manager::Chart->find_by(id => $acc_trans->chart_id);
 358
 359   return $reference_account;
 360 };
 361
 362 sub reference_amount {
 363   my $self = shift;
 364
 365   my $is_sales = ref($self) eq 'SL::DB::Invoice';
 366
 367   require SL::DB::Manager::AccTransaction;
 368
 369   my $link_filter = $is_sales ? 'AR' : 'AP';
 370
 371   my $acc_trans = SL::DB::Manager::AccTransaction->find_by(
 372      trans_id   => $self->id,
 373      SL::DB::Manager::AccTransaction->chart_link_filter("$link_filter")
 374   );
 375
 376   return undef unless ref $acc_trans;
 377
 378   # this should be the same as $self->amount
 379   return $acc_trans->amount;
 380 };
 381
 382
 383 sub open_amount {
 384   my $self = shift;
 385
 386   # in the future maybe calculate this from acc_trans
 387
 388   # if the difference is 0.01 Cent this may end up as 0.009999999999998
 389   # numerically, so round this value when checking for cent threshold >= 0.01
 390
 391   return ($self->amount // 0) - ($self->paid // 0);
 392 };
 393
 394 sub open_percent {
 395   my $self = shift;
 396
 397   return 0 if $self->amount == 0;
 398   my $open_percent;
 399   if ( $self->open_amount < 0 ) {
 400     # overpaid, currently treated identically
 401     $open_percent = $self->open_amount * 100 / $self->amount;
 402   } else {
 403     $open_percent = $self->open_amount * 100 / $self->amount;
 404   };
 405
 406   return _round($open_percent) || 0;
 407 };
 408
 409 sub skonto_amount {
 410   my $self = shift;
 411
 412   return $self->amount - $self->amount_less_skonto;
 413 };
 414
 415 sub remaining_skonto_days {
 416   my $self = shift;
 417
 418   return undef unless ref $self->skonto_date;
 419
 420   my $dur = DateTime::Duration->new($self->skonto_date - DateTime->today);
 421   return $dur->delta_days();
 422
 423 };
 424
 425 sub percent_skonto {
 426   my $self = shift;
 427
 428   my $is_sales = ref($self) eq 'SL::DB::Invoice';
 429
 430   my $percent_skonto = 0;
 431
 432   if ( $is_sales ) {
 433     return undef unless ref $self->payment_terms;
 434     return undef unless $self->payment_terms->percent_skonto > 0;
 435     $percent_skonto = $self->payment_terms->percent_skonto;
 436   } else {
 437     return undef unless ref $self->vendor->payment_terms;
 438     return undef unless $self->vendor->payment_terms->terms_skonto > 0;
 439     $percent_skonto = $self->vendor->payment_terms->percent_skonto;
 440   };
 441
 442   return $percent_skonto;
 443 };
 444
 445 sub amount_less_skonto {
 446   # amount that has to be paid if skonto applies, always return positive rounded values
 447   # the result is rounded so we can directly compare it with the user input
 448   my $self = shift;
 449
 450   my $is_sales = ref($self) eq 'SL::DB::Invoice';
 451
 452   my $percent_skonto = $self->percent_skonto || 0;
 453
 454   return _round($self->amount - ( $self->amount * $percent_skonto) );
 455
 456 };
 457
 458 sub check_skonto_configuration {
 459   my $self = shift;
 460
 461   my $is_sales = ref($self) eq 'SL::DB::Invoice';
 462
 463   my $skonto_configured = 1; # default is assume skonto works
 464
 465   # my $transactions = $self->transactions;
 466   foreach my $transaction (@{ $self->transactions }) {
 467     # find all transactions with an AR_amount or AP_amount link
 468     my $tax = SL::DB::Manager::Tax->get_first( where => [taxkey => $transaction->taxkey, id => $transaction->tax_id ]);
 469     croak "no tax for taxkey " . $transaction->{taxkey} unless ref $tax;
 470
 471     $transaction->{chartlinks} = { map { $_ => 1 } split(m/:/, $transaction->chart_link) };
 472     if ( $is_sales && $transaction->{chartlinks}->{AR_amount} ) {
 473       $skonto_configured = 0 unless $tax->skonto_sales_chart_id;
 474     } elsif ( !$is_sales && $transaction->{chartlinks}->{AP_amount}) {
 475       $skonto_configured = 0 unless $tax->skonto_purchase_chart_id;
 476     };
 477   };
 478
 479   return $skonto_configured;
 480 };
 481
 482 sub open_sepa_transfer_amount {
 483   my $self = shift;
 484
 485   my ($vc, $key, $type);
 486   if ( ref($self) eq 'SL::DB::Invoice' ) {
 487     $vc   = 'customer';
 488     $key  = 'ap_id';
 489     $type = 'ar';
 490   } else {
 491     $vc   = 'vendor';
 492     $key  = 'ap_id';
 493     $type = 'ap';
 494   };
 495
 496   my $sql = qq|SELECT SUM(sei.amount) AS amount FROM sepa_export_items sei | .
 497             qq| LEFT JOIN sepa_export se ON (sei.sepa_export_id = se.id)   | .
 498             qq| WHERE $key = ? AND NOT se.closed AND (se.vc = '$vc')       |;
 499
 500   my ($open_sepa_amount) = $self->db->dbh->selectrow_array($sql, undef, $self->id);
 501
 502   return $open_sepa_amount || 0;
 503
 504 };
 505
 506
 507 sub skonto_charts {
 508   my $self = shift;
 509
 510   # TODO: use param for amount, may also want to calculate skonto_amounts by
 511   # passing percentage in the future
 512
 513   my $amount = shift || $self->skonto_amount;
 514
 515   croak "no amount passed to skonto_charts" unless abs(_round($amount)) >= 0.01;
 516
 517   # TODO: check whether there are negative values in invoice / acc_trans ... credited items
 518
 519   # don't check whether skonto applies, because user may want to override this
 520   # return undef unless $self->percent_skonto;  # for is_sales
 521   # return undef unless $self->vendor->payment_terms->percent_skonto;  # for purchase
 522
 523   my $is_sales = ref($self) eq 'SL::DB::Invoice';
 524
 525   my $mult = $is_sales ? 1 : -1;  # multiplier for getting the right sign
 526
 527   my @skonto_charts;  # resulting array with all income/expense accounts that have to be corrected
 528
 529   # calculate effective skonto (percentage) in difference_as_skonto mode
 530   # only works if there are no negative acc_trans values
 531   my $effective_skonto_rate = $amount ? $amount / $self->amount : 0;
 532
 533   # checks:
 534   my $total_skonto_amount  = 0;
 535   my $total_rounding_error = 0;
 536
 537   my $reference_ARAP_amount = 0;
 538
 539   # my $transactions = $self->transactions;
 540   foreach my $transaction (@{ $self->transactions }) {
 541     # find all transactions with an AR_amount or AP_amount link
 542     $transaction->{chartlinks} = { map { $_ => 1 } split(m/:/, $transaction->{chart_link}) };
 543     # second condition is that we can determine an automatic Skonto account for each AR_amount entry
 544
 545     if ( ( $is_sales && $transaction->{chartlinks}->{AR_amount} ) or ( !$is_sales && $transaction->{chartlinks}->{AP_amount}) ) {
 546         # $reference_ARAP_amount += $transaction->{amount} * $mult;
 547
 548         # quick hack that works around problem of non-unique tax keys in SKR04
 549         # ? use tax_id in acc_trans
 550         my $tax = SL::DB::Manager::Tax->get_first( where => [id => $transaction->{tax_id}]);
 551         croak "no tax for taxkey " . $transaction->{taxkey} unless ref $tax;
 552
 553         if ( $is_sales ) {
 554           die t8('no skonto_chart configured for taxkey #1 : #2 : #3', $transaction->{taxkey} , $tax->taxdescription , $tax->rate*100) unless ref $tax->skonto_sales_chart;
 555         } else {
 556           die t8('no skonto_chart configured for taxkey #1 : #2 : #3', $transaction->{taxkey} , $tax->taxdescription , $tax->rate*100) unless ref $tax->skonto_purchase_chart;
 557         };
 558
 559         my $skonto_amount_unrounded;
 560
 561         my $skonto_percent_abs = $self->amount ? abs($transaction->amount * (1 + $tax->rate) * 100 / $self->amount) : 0;
 562
 563         my $transaction_amount = abs($transaction->{amount} * (1 + $tax->rate));
 564         my $transaction_skonto_percent = abs($transaction_amount/$self->amount); # abs($transaction->{amount} * (1 + $tax->rate));
 565
 566
 567         $skonto_amount_unrounded   = abs($amount * $transaction_skonto_percent);
 568         my $skonto_amount_rounded  = _round($skonto_amount_unrounded);
 569         my $rounding_error         = $skonto_amount_unrounded - $skonto_amount_rounded;
 570         my $rounded_rounding_error = _round($rounding_error);
 571
 572         $total_rounding_error += $rounding_error;
 573         $total_skonto_amount  += $skonto_amount_rounded;
 574
 575         my $rec = {
 576           # skonto_percent_abs: relative part of amount + tax to the total invoice amount
 577           'skonto_percent_abs'     => $skonto_percent_abs,
 578           'chart_id'               => $is_sales ? $tax->skonto_sales_chart->id : $tax->skonto_purchase_chart->id,
 579           'skonto_amount'          => $skonto_amount_rounded,
 580           # 'rounding_error'         => $rounding_error,
 581           # 'rounded_rounding_error' => $rounded_rounding_error,
 582         };
 583
 584         push @skonto_charts, $rec;
 585       };
 586   };
 587
 588   # if the rounded sum of all rounding_errors reaches 0.01 this sum is
 589   # subtracted from the largest skonto_amount
 590   my $rounded_total_rounding_error = abs(_round($total_rounding_error));
 591
 592   if ( $rounded_total_rounding_error > 0 ) {
 593     my $highest_amount_pos = 0;
 594     my $highest_amount = 0;
 595     my $i = -1;
 596     foreach my $ref ( @skonto_charts ) {
 597       $i++;
 598       if ( $ref->{skonto_amount} > $highest_amount ) {
 599         $highest_amount     = $ref->{skonto_amount};
 600         $highest_amount_pos = $i;
 601       };
 602     };
 603     $skonto_charts[$i]->{skonto_amount} -= $rounded_total_rounding_error;
 604   };
 605
 606   return @skonto_charts;
 607 };
 608
 609
 610 sub within_skonto_period {
 611   my $self = shift;
 612   my $dateref = shift || DateTime->now->truncate( to => 'day' );
 613
 614   return undef unless ref $dateref eq 'DateTime';
 615   return 0 unless $self->skonto_date;
 616
 617   # return 1 if requested date (or today) is inside skonto period
 618   # this will also return 1 if date is before the invoice date
 619   return $dateref <= $self->skonto_date;
 620 };
 621
 622 sub valid_skonto_amount {
 623   my $self = shift;
 624   my $amount = shift || 0;
 625   my $max_skonto_percent = 0.10;
 626
 627   return 0 unless $amount > 0;
 628
 629   # does this work for other currencies?
 630   return ($self->amount*$max_skonto_percent) > $amount;
 631 };
 632
 633 sub get_payment_select_options_for_bank_transaction {
 634   my ($self, $bt_id, %params) = @_;
 635
 636   # no skonto date  -> no select option
 637   return { payment_type => 'without_skonto', display => t8('without skonto') , selected => 1 } unless $self->skonto_date;
 638
 639   my $bt = SL::DB::BankTransaction->new(id => $bt_id)->load;
 640
 641   my @options;
 642
 643   if ($self->skonto_date && $self->within_skonto_period($bt->transdate)) {
 644     push(@options, { payment_type => 'without_skonto', display => t8('without skonto') });
 645     push(@options, { payment_type => 'with_skonto_pt', display => t8('with skonto acc. to pt'), selected => 1 });
 646   } else {
 647     push(@options, { payment_type => 'without_skonto', display => t8('without skonto') , selected => 1 });
 648     push(@options, { payment_type => 'with_skonto_pt', display => t8('with skonto acc. to pt')});
 649   }
 650   return @options;
 651 }
 652
 653 sub exchangerate {
 654   my ($self) = @_;
 655
 656   return 1 if $self->currency_id == $::instance_conf->get_currency_id;
 657
 658   die "transdate isn't a DateTime object:" . ref($self->transdate) unless ref($self->transdate) eq 'DateTime';
 659   my $rate = SL::DB::Manager::Exchangerate->find_by(currency_id => $self->currency_id,
 660                                                     transdate   => $self->transdate,
 661                                                    );
 662   return undef unless $rate;
 663
 664   return $self->is_sales ? $rate->buy : $rate->sell; # also undef if not defined
 665 };
 666
 667 sub get_payment_suggestions {
 668
 669   my ($self, %params) = @_;
 670
 671   my $open_amount = $self->open_amount;
 672   $open_amount   -= $self->open_sepa_transfer_amount if $params{sepa};
 673
 674   $self->{invoice_amount_suggestion} = $open_amount;
 675   undef $self->{payment_select_options};
 676   push(@{$self->{payment_select_options}} , { payment_type => 'without_skonto',  display => t8('without skonto') });
 677   if ( $self->within_skonto_period ) {
 678     # If there have been no payments yet suggest amount_less_skonto, otherwise the open amount
 679     if ( $open_amount &&                   # invoice amount not 0
 680          $open_amount == $self->amount &&  # no payments yet, or sum of payments and sepa export amounts is zero
 681          $self->check_skonto_configuration) {
 682       $self->{invoice_amount_suggestion} = $self->amount_less_skonto;
 683       push(@{$self->{payment_select_options}} , { payment_type => 'with_skonto_pt',  display => t8('with skonto acc. to pt') , selected => 1 });
 684     } else {
 685       if ( ( $self->valid_skonto_amount($self->open_amount) || $self->valid_skonto_amount($open_amount) ) and not $params{sepa} ) {
 686         $self->{invoice_amount_suggestion} = $open_amount;
 687         # only suggest difference_as_skonto if open_amount exactly matches skonto_amount
 688         # AND we aren't in SEPA mode
 689         my $selected = 0;
 690         $selected = 1 if _round($open_amount) == _round($self->skonto_amount);
 691         push(@{$self->{payment_select_options}} , { payment_type => 'difference_as_skonto',  display => t8('difference as skonto') , selected => $selected });
 692       };
 693     };
 694   } else {
 695     # invoice was configured with skonto, but skonto date has passed, or no skonto available
 696     $self->{invoice_amount_suggestion} = $open_amount;
 697     # difference_as_skonto doesn't make any sense for SEPA transfer, as this doesn't cause any actual payment
 698     if ( $self->valid_skonto_amount($self->open_amount) && not $params{sepa} ) {
 699       push(@{$self->{payment_select_options}} , { payment_type => 'difference_as_skonto',  display => t8('difference as skonto') , selected => 0 });
 700     };
 701   };
 702   return 1;
 703 };
 704
 705 # locales for payment type
 706 #
 707 # $main::locale->text('without_skonto')
 708 # $main::locale->text('with_skonto_pt')
 709 # $main::locale->text('difference_as_skonto')
 710 #
 711
 712 sub validate_payment_type {
 713   my $payment_type = shift;
 714
 715   my %allowed_payment_types = map { $_ => 1 } qw(without_skonto with_skonto_pt difference_as_skonto);
 716   croak "illegal payment type: $payment_type, must be one of: " . join(' ', keys %allowed_payment_types) unless $allowed_payment_types{ $payment_type };
 717
 718   return 1;
 719 }
 720
 721 sub forex {
 722   my ($self) = @_;
 723   $self->currency_id == $::instance_conf->get_currency_id ? return 0 : return 1;
 724 };
 725
 726 sub _round {
 727   my $value = shift;
 728   my $num_dec = 2;
 729   return $::form->round_amount($value, 2);
 730 }
 731
 732 1;
 733
 734 __END__
 735
 736 =pod
 737
 738 =head1 NAME
 739
 740 SL::DB::Helper::Payment  Mixin providing helper methods for paying C<Invoice>
 741                          and C<PurchaseInvoice> objects and using skonto
 742
 743 =head1 SYNOPSIS
 744
 745 In addition to actually causing a payment via pay_invoice this helper contains
 746 many methods that help in determining information about the status of the
 747 invoice, such as the remaining open amount, whether skonto applies, until which
 748 date skonto applies, the skonto amount and relative percentages, what to do
 749 with skonto, ...
 750
 751 To prevent duplicate code this was all added in this mixin rather than directly
 752 in SL::DB::Invoice and SL::DB::PurchaseInvoice.
 753
 754 =over 4
 755
 756 =item C<pay_invoice %params>
 757
 758 Create a payment booking for an existing invoice object (type ar/ap/is/ir) via
 759 a configured bank account.
 760
 761 This function deals with all the acc_trans entries and also updates paid and datepaid.
 762
 763 Example:
 764
 765   my $ap   = SL::DB::Manager::PurchaseInvoice->find_by( invnumber => '1');
 766   my $bank = SL::DB::Manager::BankAccount->find_by( name => 'Bank');
 767   $ap->pay_invoice(chart_id      => $bank->chart_id,
 768                    amount        => $ap->open_amount,
 769                    transdate     => DateTime->now->to_kivitendo,
 770                    memo          => 'foobar',
 771                    source        => 'barfoo',
 772                    payment_type  => 'without_skonto',  # default if not specified
 773                    project_id    => 25,
 774                   );
 775
 776 or with skonto:
 777   $ap->pay_invoice(chart_id      => $bank->chart_id,
 778                    amount        => $ap->amount,       # doesn't need to be specified
 779                    transdate     => DateTime->now->to_kivitendo,
 780                    memo          => 'foobar',
 781                    source        => 'barfoo',
 782                    payment_type  => 'with_skonto',
 783                   );
 784
 785 or in a certain currency:
 786   $ap->pay_invoice(chart_id      => $bank->chart_id,
 787                    amount        => 500,
 788                    currency      => 'USD',
 789                    transdate     => DateTime->now->to_kivitendo,
 790                    memo          => 'foobar',
 791                    source        => 'barfoo',
 792                    payment_type  => 'with_skonto_pt',
 793                   );
 794
 795 Allowed payment types are:
 796   without_skonto with_skonto_pt difference_as_skonto
 797
 798 The option C<payment_type> allows for a basic skonto mechanism.
 799
 800 C<without_skonto> is the default mode, "amount" is paid to the account in
 801 chart_id. This can also be used for partial payments and corrections via
 802 negative amounts.
 803
 804 C<with_skonto_pt> can't be used for partial payments. When used on unpaid
 805 invoices the whole amount is paid, with the skonto part automatically being
 806 booked according to the skonto chart configured in the tax settings for each
 807 tax key. If an amount is passed it is ignored and the actual configured skonto
 808 amount is used.
 809
 810 C<difference_as_skonto> can only be used after partial payments have been made,
 811 the whole specified amount is booked according to the skonto charts configured
 812 in the tax settings for each tax key.
 813
 814 So passing amount doesn't have any effect for the cases C<with_skonto_pt> and
 815 C<difference_as_skonto>, as all necessary values are taken from the stored
 816 invoice.
 817
 818 The skonto modes automatically calculate the relative amounts for a mix of
 819 taxes, e.g. items with 7% and 19% in one invoice. There is a helper method
 820 skonto_charts, which calculates the relative percentages according to the
 821 amounts in acc_trans (which are grouped by tax).
 822
 823 There is currently no way of excluding certain items in an invoice from having
 824 skonto applied to them.  If this feature was added to parts the calculation
 825 method of relative skonto would have to be completely rewritten using the
 826 invoice items rather than acc_trans.
 827
 828 The skonto modes also still don't automatically correct the tax, this still has
 829 to be done manually. Therefore all payments generated by pay_invoice have
 830 taxkey 0.
 831
 832 There is currently no way to directly pay an invoice via this method if the
 833 effective skonto differs from the skonto according to the payment terms
 834 configured for the invoice/vendor.
 835
 836 In this case one has to pay in two steps: first the actual paid amount via
 837 "without skonto", and then the remainder via "difference_as_skonto". The user
 838 has to there actively decide whether to accept the differing skonto.
 839
 840 Because of the way skonto_charts works the calculation doesn't work if there
 841 are negative values in acc_trans. E.g. one invoice with a positive value for
 842 19% tax and a negative value for the acc_trans line with 7%
 843
 844 Skonto doesn't/shouldn't apply if the invoice contains credited items.
 845
 846 If no amount is given the whole open amout is paid.
 847
 848 If neither currency or currency_id are given as params, the currency of the
 849 invoice is assumed to be the payment currency.
 850
 851 If successful the return value will be 1 in scalar context or in list context
 852 the two ids (acc_trans_id) of the newly created bookings.
 853 =item C<reference_account>
 854
 855 Returns a chart object which is the chart of the invoice with link AR or AP.
 856
 857 Example (1200 is the AR account for SKR04):
 858   my $invoice = invoice(invnumber => '144');
 859   $invoice->reference_account->accno
 860   # 1200
 861
 862 =item C<percent_skonto>
 863
 864 Returns the configured skonto percentage of the payment terms of an invoice,
 865 e.g. 0.02 for 2%. Payment terms come from invoice settings for ar, from vendor
 866 settings for ap.
 867
 868 =item C<amount_less_skonto>
 869
 870 If the invoice has a payment term (via ar for sales, via vendor for purchase),
 871 calculate the amount to be paid in the case of skonto.  This doesn't check,
 872 whether skonto applies (i.e. skonto doesn't wasn't exceeded), it just subtracts
 873 the configured percentage (e.g. 2%) from the total amount.
 874
 875 The returned value is rounded to two decimals.
 876
 877 =item C<skonto_date>
 878
 879 The date up to which skonto may be taken. This is calculated from the invoice
 880 date + the number of days configured in the payment terms.
 881
 882 This method can also be used to determine whether skonto applies for the
 883 invoice, as it returns undef if there is no payment term or skonto days is set
 884 to 0.
 885
 886 =item C<within_skonto_period [DATE]>
 887
 888 Returns 0 or 1.
 889
 890 Checks whether the invoice has payment terms configured, and whether the date
 891 is within the skonto max date. If no date is passed the current date is used.
 892
 893 You can also pass a dateref object as a parameter to check whether skonto
 894 applies for that date rather than the current date.
 895
 896 =item C<valid_skonto_amount>
 897
 898 Takes an amount as an argument and checks whether the amount is less than 10%
 899 of the total amount of the invoice. The value of 10% is currently hardcoded in
 900 the method. This method is currently used to check whether to offer the payment
 901 option "difference as skonto".
 902
 903 Example:
 904  if ( $invoice->valid_skonto_amount($invoice->open_amount) ) {
 905    # ... do something
 906  }
 907
 908 =item C<skonto_charts [$amount]>
 909
 910 Returns a list of chart_ids and some calculated numbers that can be used for
 911 paying the invoice with skonto. This function will automatically calculate the
 912 relative skonto amounts even if the invoice contains several types of taxes
 913 (e.g. 7% and 19%).
 914
 915 Example usage:
 916   my $invoice = SL::DB::Manager::Invoice->find_by(invnumber => '211');
 917   my @skonto_charts = $invoice->skonto_charts;
 918
 919 or with the total skonto amount as an argument:
 920   my @skonto_charts = $invoice->skonto_charts($invoice->open_amount);
 921
 922 The following values are generated for each chart:
 923
 924 =over 2
 925
 926 =item C<chart_id>
 927
 928 The chart id of the skonto amount to be booked.
 929
 930 =item C<skonto_amount>
 931
 932 The total amount to be paid to the account
 933
 934 =item C<skonto_percent>
 935
 936 The relative percentage of that skonto chart. This can be useful if the actual
 937 ekonto that is paid deviates from the granted skonto, e.g. customer effectively
 938 pays 2.6% skonto instead of 2%, and we accept this. Then we can still calculate
 939 the relative skonto amounts for different taxes based on the absolute
 940 percentages. Used for case C<difference_as_skonto>.
 941
 942 =item C<skonto_percent_abs>
 943
 944 The absolute percentage of that skonto chart in relation to the total amount.
 945 Used to calculate skonto_amount for case C<with_skonto_pt>.
 946
 947 =back
 948
 949 If the invoice contains several types of taxes then skonto_charts can be used
 950 to calculate the relative amounts.
 951
 952 Example in console of an invoice with 100 Euro at 7% and 100 Euro at 19% with
 953 tax not included:
 954
 955   my $invoice = invoice(invnumber => '144');
 956   $invoice->amount
 957   226.00000
 958   $invoice->payment_terms->percent_skonto
 959   0.02
 960   $invoice->skonto_charts
 961   pp $invoice->skonto_charts
 962   #             $VAR1 = {
 963   #               'chart_id'       => 128,
 964   #               'skonto_amount'  => '2.14',
 965   #               'skonto_percent' => '47.3451327433627'
 966   #             };
 967   #             $VAR2 = {
 968   #               'chart_id'       => 130,
 969   #               'skonto_amount'  => '2.38',
 970   #               'skonto_percent' => '52.654867256637'
 971   #             };
 972
 973 C<skonto_charts> always returns positive values (abs) for C<skonto_amount> and
 974 C<skonto_percent>.
 975
 976 C<skonto_charts> generates one entry for each acc_trans entry. ar and ap
 977 bookings only have one acc_trans entry for each taxkey (e.g. 7% and 19%).  This
 978 is because all the items are grouped according to the Buchungsgruppen mechanism
 979 and the totals are written to acc_trans.  For is and ir it is possible to have
 980 several acc_trans entries with the same tax. In this case skonto_charts
 981 generates a skonto booking for each acc_trans income/expense entry.
 982
 983 In the future this function may also be used to calculate the corrections for
 984 the income tax.
 985
 986 =item C<open_amount>
 987
 988 Unrounded total open amount of invoice (amount - paid).
 989 Doesn't take into account pending SEPA transfers.
 990
 991 =item C<open_percent>
 992
 993 Percentage of the invoice that is still unpaid, e.g. 100,00 if no payments have
 994 been made yet, 0,00 if fully paid.
 995
 996 =item C<remaining_skonto_days>
 997
 998 How many days skonto can still be taken, calculated from current day. Returns 0
 999 if current day is the max skonto date, and negative number if skonto date has
1000 already passed.
1001
1002 Returns undef if skonto is not configured for that invoice.
1003
1004 =item C<get_payment_suggestions %params>
1005
1006 Creates data intended for an L.select_tag dropdown that can be used in a
1007 template. Depending on the rules it will choose from the options
1008 without_skonto, with_skonto_pt and difference_as_skonto, and select the most
1009 likely one.
1010
1011 If the parameter "sepa" is passed, the SEPA export payments that haven't been
1012 executed yet are considered when determining the open amount of the invoice.
1013
1014 The current rules are:
1015
1016 =over 2
1017
1018 =item * without_skonto is always an option
1019
1020 =item * with_skonto_pt is only offered if there haven't been any payments yet and the current date is within the skonto period.
1021
1022 =item * difference_as_skonto is only offered if there have already been payments made and the open amount is smaller than 10% of the total amount.
1023
1024 with_skonto_pt will only be offered, if all the AR_amount/AP_amount have a
1025 taxkey with a configured skonto chart
1026
1027 =back
1028
1029 It will also fill $self->{invoice_amount_suggestion} with either the open
1030 amount, or if with_skonto_pt is selected, with amount_less_skonto, so the
1031 template can fill the input with the likely amount.
1032
1033 Example in console:
1034   my $ar = invoice( invnumber => '257');
1035   $ar->get_payment_suggestions;
1036   print $ar->{invoice_amount_suggestion} . "\n";
1037   # 97.23
1038   pp $ar->{payment_select_options}
1039   # $VAR1 = [
1040   #         {
1041   #           'display' => 'ohne Skonto',
1042   #           'payment_type' => 'without_skonto'
1043   #         },
1044   #         {
1045   #           'display' => 'mit Skonto nach ZB',
1046   #           'payment_type' => 'with_skonto_pt',
1047   #           'selected' => 1
1048   #         }
1049   #       ];
1050
1051 The resulting array $ar->{payment_select_options} can be used in a template
1052 select_tag using value_key and title_key:
1053
1054 [% L.select_tag('payment_type_' _ loop.count, invoice.payment_select_options, value_key => 'payment_type', title_key => 'display', id => 'payment_type_' _ loop.count) %]
1055
1056 It would probably make sense to have different rules for the pre-selected items
1057 for sales and purchase, and to also make these rules configurable in the
1058 defaults. E.g. when creating a SEPA bank transfer for vendor invoices a company
1059 might always want to pay quickly making use of skonto, while another company
1060 might always want to pay as late as possible.
1061
1062 =item C<get_payment_select_options_for_bank_transaction $banktransaction_id %params>
1063
1064 Make suggestion for a skonto payment type by returning an HTML blob of the options
1065 of a HTML drop-down select with the most likely option preselected.
1066
1067 This is a helper function for BankTransaction/ajax_payment_suggestion and
1068 template/webpages/bank_transactions/invoices.html
1069
1070 We are working with an existing payment, so difference_as_skonto never makes sense.
1071
1072 If skonto is not possible (skonto_date does not exists) simply return
1073 the single 'no skonto' option as a visual hint.
1074
1075 If skonto is possible (skonto_date exists), add two possibilities:
1076 without_skonto and with_skonto_pt if payment date is within skonto_date,
1077 preselect with_skonto_pt, otherwise preselect without skonto.
1078
1079 =item C<exchangerate>
1080
1081 Returns 1 immediately if the record uses the default currency.
1082
1083 Returns the exchangerate in database format for the invoice according to that
1084 invoice's transdate, returning 'buy' for sales, 'sell' for purchases.
1085
1086 If no exchangerate can be found for that day undef is returned.
1087
1088 =item C<forex>
1089
1090 Returns 1 if record uses a different currency, 0 if the default currency is used.
1091
1092 =back
1093
1094 =head1 TODO AND CAVEATS
1095
1096 =over 4
1097
1098 =item *
1099
1100 when looking at open amount, maybe consider that there may already be queued
1101 amounts in SEPA Export
1102
1103 =back
1104
1105 =head1 AUTHOR
1106
1107 G. Richardson E<lt>grichardson@kivitendo-premium.de<gt>
1108
1109 =cut