FS/FS/cust_bill.pm

   1 package FS::cust_bill;
   2
   3 use strict;
   4 use vars qw( @ISA $conf $invoice_template $money_char );
   5 use vars qw( $invoice_lines @buf ); #yuck
   6 use Date::Format;
   7 use Text::Template;
   8 use FS::Record qw( qsearch qsearchs );
   9 use FS::cust_main;
  10 use FS::cust_bill_pkg;
  11 use FS::cust_credit;
  12 use FS::cust_pay;
  13 use FS::cust_pkg;
  14 use FS::cust_credit_bill;
  15
  16 @ISA = qw( FS::Record );
  17
  18 #ask FS::UID to run this stuff for us later
  19 $FS::UID::callback{'FS::cust_bill'} = sub {
  20
  21   $conf = new FS::Conf;
  22
  23   $money_char = $conf->config('money_char') || '$';
  24
  25   my @invoice_template = $conf->config('invoice_template')
  26     or die "cannot load config file invoice_template";
  27   $invoice_lines = 0;
  28   foreach ( grep /invoice_lines\(\d+\)/, @invoice_template ) { #kludgy
  29     /invoice_lines\((\d+)\)/;
  30     $invoice_lines += $1;
  31   }
  32   die "no invoice_lines() functions in template?" unless $invoice_lines;
  33   $invoice_template = new Text::Template (
  34     TYPE   => 'ARRAY',
  35     SOURCE => [ map "$_\n", @invoice_template ],
  36   ) or die "can't create new Text::Template object: $Text::Template::ERROR";
  37   $invoice_template->compile()
  38     or die "can't compile template: $Text::Template::ERROR";
  39 };
  40
  41 =head1 NAME
  42
  43 FS::cust_bill - Object methods for cust_bill records
  44
  45 =head1 SYNOPSIS
  46
  47   use FS::cust_bill;
  48
  49   $record = new FS::cust_bill \%hash;
  50   $record = new FS::cust_bill { 'column' => 'value' };
  51
  52   $error = $record->insert;
  53
  54   $error = $new_record->replace($old_record);
  55
  56   $error = $record->delete;
  57
  58   $error = $record->check;
  59
  60   ( $total_previous_balance, @previous_cust_bill ) = $record->previous;
  61
  62   @cust_bill_pkg_objects = $cust_bill->cust_bill_pkg;
  63
  64   ( $total_previous_credits, @previous_cust_credit ) = $record->cust_credit;
  65
  66   @cust_pay_objects = $cust_bill->cust_pay;
  67
  68   $tax_amount = $record->tax;
  69
  70   @lines = $cust_bill->print_text;
  71   @lines = $cust_bill->print_text $time;
  72
  73 =head1 DESCRIPTION
  74
  75 An FS::cust_bill object represents an invoice; a declaration that a customer
  76 owes you money.  The specific charges are itemized as B<cust_bill_pkg> records
  77 (see L<FS::cust_bill_pkg>).  FS::cust_bill inherits from FS::Record.  The
  78 following fields are currently supported:
  79
  80 =over 4
  81
  82 =item invnum - primary key (assigned automatically for new invoices)
  83
  84 =item custnum - customer (see L<FS::cust_main>)
  85
  86 =item _date - specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
  87 L<Time::Local> and L<Date::Parse> for conversion functions.
  88
  89 =item charged - amount of this invoice
  90
  91 =item printed - how many times this invoice has been printed automatically
  92 (see L<FS::cust_main/"collect">).
  93
  94 =back
  95
  96 =head1 METHODS
  97
  98 =over 4
  99
 100 =item new HASHREF
 101
 102 Creates a new invoice.  To add the invoice to the database, see L<"insert">.
 103 Invoices are normally created by calling the bill method of a customer object
 104 (see L<FS::cust_main>).
 105
 106 =cut
 107
 108 sub table { 'cust_bill'; }
 109
 110 =item insert
 111
 112 Adds this invoice to the database ("Posts" the invoice).  If there is an error,
 113 returns the error, otherwise returns false.
 114
 115 =item delete
 116
 117 Currently unimplemented.  I don't remove invoices because there would then be
 118 no record you ever posted this invoice (which is bad, no?)
 119
 120 =cut
 121
 122 sub delete {
 123   return "Can't remove invoice!"
 124 }
 125
 126 =item replace OLD_RECORD
 127
 128 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 129 returns the error, otherwise returns false.
 130
 131 Only printed may be changed.  printed is normally updated by calling the
 132 collect method of a customer object (see L<FS::cust_main>).
 133
 134 =cut
 135
 136 sub replace {
 137   my( $new, $old ) = ( shift, shift );
 138   return "Can't change custnum!" unless $old->custnum == $new->custnum;
 139   #return "Can't change _date!" unless $old->_date eq $new->_date;
 140   return "Can't change _date!" unless $old->_date == $new->_date;
 141   return "Can't change charged!" unless $old->charged == $new->charged;
 142
 143   $new->SUPER::replace($old);
 144 }
 145
 146 =item check
 147
 148 Checks all fields to make sure this is a valid invoice.  If there is an error,
 149 returns the error, otherwise returns false.  Called by the insert and replace
 150 methods.
 151
 152 =cut
 153
 154 sub check {
 155   my $self = shift;
 156
 157   my $error =
 158     $self->ut_numbern('invnum')
 159     || $self->ut_number('custnum')
 160     || $self->ut_numbern('_date')
 161     || $self->ut_money('charged')
 162     || $self->ut_numbern('printed')
 163   ;
 164   return $error if $error;
 165
 166   return "Unknown customer"
 167     unless qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
 168
 169   $self->_date(time) unless $self->_date;
 170
 171   $self->printed(0) if $self->printed eq '';
 172
 173   ''; #no error
 174 }
 175
 176 =item previous
 177
 178 Returns a list consisting of the total previous balance for this customer,
 179 followed by the previous outstanding invoices (as FS::cust_bill objects also).
 180
 181 =cut
 182
 183 sub previous {
 184   my $self = shift;
 185   my $total = 0;
 186   my @cust_bill = sort { $a->_date <=> $b->_date }
 187     grep { $_->owed != 0 && $_->_date < $self->_date }
 188       qsearch( 'cust_bill', { 'custnum' => $self->custnum } )
 189   ;
 190   foreach ( @cust_bill ) { $total += $_->owed; }
 191   $total, @cust_bill;
 192 }
 193
 194 =item cust_bill_pkg
 195
 196 Returns the line items (see L<FS::cust_bill_pkg>) for this invoice.
 197
 198 =cut
 199
 200 sub cust_bill_pkg {
 201   my $self = shift;
 202   qsearch( 'cust_bill_pkg', { 'invnum' => $self->invnum } );
 203 }
 204
 205 =item cust_credit
 206
 207 Depreciated.  See the cust_credited method.
 208
 209  #Returns a list consisting of the total previous credited (see
 210  #L<FS::cust_credit>) and unapplied for this customer, followed by the previous
 211  #outstanding credits (FS::cust_credit objects).
 212
 213 =cut
 214
 215 sub cust_credit {
 216   use Carp;
 217   croak "FS::cust_bill->cust_credit depreciated; see ".
 218         "FS::cust_bill->cust_credit_bill";
 219   #my $self = shift;
 220   #my $total = 0;
 221   #my @cust_credit = sort { $a->_date <=> $b->_date }
 222   #  grep { $_->credited != 0 && $_->_date < $self->_date }
 223   #    qsearch('cust_credit', { 'custnum' => $self->custnum } )
 224   #;
 225   #foreach (@cust_credit) { $total += $_->credited; }
 226   #$total, @cust_credit;
 227 }
 228
 229 =item cust_pay
 230
 231 Depreciated.  See the cust_bill_pay method.
 232
 233 #Returns all payments (see L<FS::cust_pay>) for this invoice.
 234
 235 =cut
 236
 237 sub cust_pay {
 238   use Carp;
 239   croak "FS::cust_bill->cust_pay depreciated; see FS::cust_bill->cust_bill_pay";
 240   #my $self = shift;
 241   #sort { $a->_date <=> $b->_date }
 242   #  qsearch( 'cust_pay', { 'invnum' => $self->invnum } )
 243   #;
 244 }
 245
 246 =item cust_bill_pay
 247
 248 Returns all payment applications (see L<FS::cust_bill_pay>) for this invoice.
 249
 250 =cut
 251
 252 sub cust_bill_pay {
 253   my $self = shift;
 254   sort { $a->_date <=> $b->_date }
 255     qsearch( 'cust_bill_pay', { 'invnum' => $self->invnum } );
 256 }
 257
 258 =item cust_credited
 259
 260 Returns all applied credits (see L<FS::cust_credit_bill>) for this invoice.
 261
 262 =cut
 263
 264 sub cust_credited {
 265   my $self = shift;
 266   sort { $a->_date <=> $b->_date }
 267     qsearch( 'cust_credit_bill', { 'invnum' => $self->invnum } )
 268   ;
 269 }
 270
 271 =item tax
 272
 273 Returns the tax amount (see L<FS::cust_bill_pkg>) for this invoice.
 274
 275 =cut
 276
 277 sub tax {
 278   my $self = shift;
 279   my $total = 0;
 280   my @taxlines = qsearch( 'cust_bill_pkg', { 'invnum' => $self->invnum ,
 281                                              'pkgnum' => 0 } );
 282   foreach (@taxlines) { $total += $_->setup; }
 283   $total;
 284 }
 285
 286 =item owed
 287
 288 Returns the amount owed (still outstanding) on this invoice, which is charged
 289 minus all payment applications (see L<FS::cust_bill_pay>) and credit
 290 applications (see L<FS::cust_credit_bill>).
 291
 292 =cut
 293
 294 sub owed {
 295   my $self = shift;
 296   my $balance = $self->charged;
 297   $balance -= $_->amount foreach ( $self->cust_bill_pay );
 298   $balance -= $_->amount foreach ( $self->cust_credited );
 299   $balance = sprintf( "%.2f", $balance);
 300   $balance =~ s/^\-0\.00$/0.00/; #yay ieee fp
 301   $balance;
 302 }
 303
 304 =item print_text [TIME];
 305
 306 Returns an text invoice, as a list of lines.
 307
 308 TIME an optional value used to control the printing of overdue messages.  The
 309 default is now.  It isn't the date of the invoice; that's the `_date' field.
 310 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
 311 L<Time::Local> and L<Date::Parse> for conversion functions.
 312
 313 =cut
 314
 315 sub print_text {
 316
 317   my( $self, $today ) = ( shift, shift );
 318   $today ||= time;
 319 #  my $invnum = $self->invnum;
 320   my $cust_main = qsearchs('cust_main', { 'custnum', $self->custnum } );
 321   $cust_main->payname( $cust_main->first. ' '. $cust_main->getfield('last') )
 322     unless $cust_main->payname;
 323
 324   my( $pr_total, @pr_cust_bill ) = $self->previous; #previous balance
 325 #  my( $cr_total, @cr_cust_credit ) = $self->cust_credit; #credits
 326   #my $balance_due = $self->owed + $pr_total - $cr_total;
 327   my $balance_due = $self->owed + $pr_total;
 328
 329   #my @collect = ();
 330   #my($description,$amount);
 331   @buf = ();
 332
 333   #previous balance
 334   foreach ( @pr_cust_bill ) {
 335     push @buf, [
 336       "Previous Balance, Invoice #". $_->invnum.
 337                  " (". time2str("%x",$_->_date). ")",
 338       $money_char. sprintf("%10.2f",$_->owed)
 339     ];
 340   }
 341   if (@pr_cust_bill) {
 342     push @buf,['','-----------'];
 343     push @buf,[ 'Total Previous Balance',
 344                 $money_char. sprintf("%10.2f",$pr_total ) ];
 345     push @buf,['',''];
 346   }
 347
 348   #new charges
 349   foreach ( $self->cust_bill_pkg ) {
 350
 351     if ( $_->pkgnum ) {
 352
 353       my($cust_pkg)=qsearchs('cust_pkg', { 'pkgnum', $_->pkgnum } );
 354       my($part_pkg)=qsearchs('part_pkg',{'pkgpart'=>$cust_pkg->pkgpart});
 355       my($pkg)=$part_pkg->pkg;
 356
 357       if ( $_->setup != 0 ) {
 358         push @buf, [ "$pkg Setup", $money_char. sprintf("%10.2f",$_->setup) ];
 359         push @buf,
 360           map { [ "  ". $_->[0]. ": ". $_->[1], '' ] } $cust_pkg->labels;
 361       }
 362
 363       if ( $_->recur != 0 ) {
 364         push @buf, [
 365           "$pkg (" . time2str("%x",$_->sdate) . " - " .
 366                                 time2str("%x",$_->edate) . ")",
 367           $money_char. sprintf("%10.2f",$_->recur)
 368         ];
 369         push @buf,
 370           map { [ "  ". $_->[0]. ": ". $_->[1], '' ] } $cust_pkg->labels;
 371       }
 372
 373     } else { #pkgnum Tax
 374       push @buf,["Tax", $money_char. sprintf("%10.2f",$_->setup) ]
 375         if $_->setup != 0;
 376     }
 377   }
 378
 379   push @buf,['','-----------'];
 380   push @buf,['Total New Charges',
 381              $money_char. sprintf("%10.2f",$self->charged) ];
 382   push @buf,['',''];
 383
 384   push @buf,['','-----------'];
 385   push @buf,['Total Charges',
 386              $money_char. sprintf("%10.2f",$self->charged + $pr_total) ];
 387   push @buf,['',''];
 388
 389   #credits
 390   foreach ( $self->cust_credited ) {
 391
 392     #something more elaborate if $_->amount ne $_->cust_credit->credited ?
 393
 394     my $reason = substr($_->cust_credit->reason,0,32);
 395     $reason .= '...' if length($reason) < length($_->cust_credit->reason);
 396     $reason = " ($reason) " if $reason;
 397     push @buf,[
 398       "Credit #". $_->crednum. " (". time2str("%x",$_->cust_credit->_date) .")".
 399         $reason,
 400       $money_char. sprintf("%10.2f",$_->amount)
 401     ];
 402   }
 403   #foreach ( @cr_cust_credit ) {
 404   #  push @buf,[
 405   #    "Credit #". $_->crednum. " (" . time2str("%x",$_->_date) .")",
 406   #    $money_char. sprintf("%10.2f",$_->credited)
 407   #  ];
 408   #}
 409
 410   #get & print payments
 411   foreach ( $self->cust_bill_pay ) {
 412
 413     #something more elaborate if $_->amount ne ->cust_pay->paid ?
 414
 415     push @buf,[
 416       "Payment received ". time2str("%x",$_->cust_pay->_date ),
 417       $money_char. sprintf("%10.2f",$_->amount )
 418     ];
 419   }
 420
 421   #balance due
 422   push @buf,['','-----------'];
 423   push @buf,['Balance Due', $money_char.
 424     sprintf("%10.2f", $balance_due ) ];
 425
 426   #setup template variables
 427
 428   package FS::cust_bill::_template; #!
 429   use vars qw( $invnum $date $page $total_pages @address $overdue @buf );
 430
 431   $invnum = $self->invnum;
 432   $date = $self->_date;
 433   $page = 1;
 434
 435   $total_pages =
 436     int( scalar(@FS::cust_bill::buf) / $FS::cust_bill::invoice_lines );
 437   $total_pages++
 438     if scalar(@FS::cust_bill::buf) % $FS::cust_bill::invoice_lines;
 439
 440
 441   #format address (variable for the template)
 442   my $l = 0;
 443   @address = ( '', '', '', '', '', '' );
 444   package FS::cust_bill; #!
 445   $FS::cust_bill::_template::address[$l++] =
 446     $cust_main->payname.
 447       ( ( $cust_main->payby eq 'BILL' ) && $cust_main->payinfo
 448         ? " (P.O. #". $cust_main->payinfo. ")"
 449         : ''
 450       )
 451   ;
 452   $FS::cust_bill::_template::address[$l++] = $cust_main->company
 453     if $cust_main->company;
 454   $FS::cust_bill::_template::address[$l++] = $cust_main->address1;
 455   $FS::cust_bill::_template::address[$l++] = $cust_main->address2
 456     if $cust_main->address2;
 457   $FS::cust_bill::_template::address[$l++] =
 458     $cust_main->city. ", ". $cust_main->state. "  ".  $cust_main->zip;
 459   $FS::cust_bill::_template::address[$l++] = $cust_main->country
 460     unless $cust_main->country eq 'US';
 461
 462   #overdue? (variable for the template)
 463   $FS::cust_bill::_template::overdue = (
 464     $balance_due > 0
 465     && $today > $self->_date
 466 #    && $self->printed > 1
 467     && $self->printed > 0
 468   );
 469
 470   #and subroutine for the template
 471
 472   sub FS::cust_bill::_template::invoice_lines {
 473     my $lines = shift;
 474     map {
 475       scalar(@buf) ? shift @buf : [ '', '' ];
 476     }
 477     ( 1 .. $lines );
 478   }
 479
 480   $FS::cust_bill::_template::page = 1;
 481   my $lines;
 482   my @collect;
 483   while (@buf) {
 484     push @collect, split("\n",
 485       $invoice_template->fill_in( PACKAGE => 'FS::cust_bill::_template' )
 486     );
 487     $FS::cust_bill::_template::page++;
 488   }
 489
 490   map "$_\n", @collect;
 491
 492 }
 493
 494 =back
 495
 496 =head1 VERSION
 497
 498 $Id: cust_bill.pm,v 1.14 2001-12-21 21:40:24 ivan Exp $
 499
 500 =head1 BUGS
 501
 502 The delete method.
 503
 504 print_text formatting (and some logic :/) is in source, but needs to be
 505 slurped in from a file.  Also number of lines ($=).
 506
 507 missing print_ps for a nice postscript copy (maybe HylaFAX-cover-page-style
 508 or something similar so the look can be completely customized?)
 509
 510 =head1 SEE ALSO
 511
 512 L<FS::Record>, L<FS::cust_main>, L<FS::cust_bill_pay>, L<FS:;cust_pay>,
 513 L<FS::cust_bill_pkg>, L<FS::cust_bill_credit>, schema.html from the base
 514 documentation.
 515
 516 =cut
 517
 518 1;
 519