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