FS/FS/TaxEngine.pm

   1 package FS::TaxEngine;
   2
   3 use strict;
   4 use vars qw( $DEBUG );
   5 use FS::Conf;
   6 use FS::Record qw(qsearch qsearchs);
   7
   8 $DEBUG = 0;
   9
  10 =head1 NAME
  11
  12 FS::TaxEngine - Base class for tax calculation engines.
  13
  14 =head1 USAGE
  15
  16 1. At the start of creating an invoice, create an FS::TaxEngine object.
  17 2. Each time a sale item is added to the invoice, call L</add_sale> on the
  18    TaxEngine.
  19 3. Set the "pending" flag on the invoice.
  20 4. Insert the invoice and its line items.
  21
  22 - If the TaxEngine is "batch" style (Billsoft):
  23 5. After creating all invoices for the day, call
  24    FS::TaxEngine::process_tax_batch.  This will create the tax items for
  25    all of the pending invoices, clear the "pending" flag, and call
  26    L<FS::cust_main::Billing/collect> on each of the billed customers.
  27
  28 - If not (the internal tax system, CCH):
  29 5. After adding all sale items, call L</calculate_taxes> on the TaxEngine to
  30    produce a list of tax line items.
  31 6. Append the tax line items to the invoice.
  32 7. Update the invoice with the new charged amount and clear the pending flag.
  33
  34 =head1 CLASS METHODS
  35
  36 =over 4
  37
  38 =item new 'cust_main' => CUST_MAIN, 'invoice_time' => TIME, OPTIONS...
  39
  40 Creates an L<FS::TaxEngine> object.  The subclass will be chosen by the
  41 'enable_taxproducts' configuration setting.
  42
  43 CUST_MAIN and TIME are required.  OPTIONS can include:
  44
  45 "cancel" => 1 to indicate that the package is being billed on cancellation.
  46
  47 "estimate" => 1 to indicate that this calculation is for tax estimation,
  48 and isn't an actual sale invoice, in case that matters.
  49
  50 =cut
  51
  52 sub new {
  53   my $class = shift;
  54   my %opt = @_;
  55   my $conf = FS::Conf->new;
  56   if ($class eq 'FS::TaxEngine') {
  57     my $subclass = $conf->config('enable_taxproducts') || 'internal';
  58     $class .= "::$subclass";
  59     local $@;
  60     eval "use $class";
  61     die "couldn't load $class: $@\n" if $@;
  62   }
  63   my $self = { items => [], taxes => {}, conf => $conf, %opt };
  64   bless $self, $class;
  65 }
  66
  67 =item info
  68
  69 Returns a hashref of metadata about this tax method, including:
  70 - batch: whether this is a batch-style engine (requires different usage)
  71 - override: whether this engine uses tax overrides
  72 - manual_tax_location: whether this engine requires the user to select a "tax
  73   location" separate from the address/city/state/zip fields
  74 - rate_table: the table that stores the tax rates
  75   (the 'taxline' method of that class will be used to calculate line-item
  76    taxes)
  77 - link_table: the table that links L<FS::cust_bill_pkg> records for taxes
  78   to the C<rate_table> entry that generated them, and to the item they
  79   represent tax on.
  80
  81 =back
  82
  83 =head1 METHODS
  84
  85 =over 4
  86
  87 =item add_sale CUST_BILL_PKG
  88
  89 Adds the CUST_BILL_PKG object as a taxable sale on this invoice.
  90
  91 =item calculate_taxes INVOICE
  92
  93 Calculates the taxes on the taxable sales and returns a list of
  94 L<FS::cust_bill_pkg> objects to add to the invoice.  The base implementation
  95 is to call L</make_taxlines> to produce a list of "raw" tax line items,
  96 then L</consolidate_taxlines> to combine those with the same itemdesc.
  97
  98 If this fails, it will throw an exception. (Accordingly it should not trap
  99 exceptions from internal methods that it calls, except to translate error
 100 messages into a more meaningful form.) If it succeeds, it MUST return an
 101 arrayref (even if the arrayref is empty).
 102
 103 =cut
 104
 105 sub calculate_taxes {
 106   my $self = shift;
 107   my $cust_bill = shift;
 108
 109   my @raw_taxlines = $self->make_taxlines($cust_bill);
 110
 111   my @real_taxlines = $self->consolidate_taxlines(@raw_taxlines);
 112
 113   if ( $cust_bill and $cust_bill->get('invnum') ) {
 114     $_->set('invnum', $cust_bill->get('invnum')) foreach @real_taxlines;
 115   }
 116   return \@real_taxlines;
 117 }
 118
 119 sub make_taxlines {
 120   my $self = shift;
 121   my $conf = $self->{conf};
 122
 123   my $cust_bill = shift;
 124
 125   my @taxlines;
 126
 127   # For each distinct tax rate definition, calculate the tax and exemptions.
 128   foreach my $taxnum ( keys %{ $self->{taxes} } ) {
 129
 130     my $taxables = $self->{taxes}{$taxnum};
 131     my $tax_object = shift @$taxables;
 132     # $tax_object is a cust_main_county or tax_rate
 133     # (with billpkgnum, pkgnum, locationnum set)
 134     # the rest of @{ $taxlisthash->{$tax} } is cust_bill_pkg component objects
 135     # (setup, recurring, usage classes)
 136
 137     my $taxline = $self->taxline('tax' => $tax_object, 'sales' => $taxables);
 138     # taxline methods are now required to return real line items
 139     # with their link records
 140     die $taxline unless ref($taxline);
 141
 142     push @taxlines, $taxline;
 143
 144   } #foreach $taxnum
 145
 146   return @taxlines;
 147 }
 148
 149 sub consolidate_taxlines {
 150
 151   my $self = shift;
 152   my $conf = $self->{conf};
 153
 154   my @raw_taxlines = @_;
 155   my @tax_line_items;
 156
 157   # keys are tax names (as printed on invoices / itemdesc )
 158   # values are arrayrefs of taxlines
 159   my %taxname;
 160   # collate these by itemdesc
 161   foreach my $taxline (@raw_taxlines) {
 162     my $taxname = $taxline->itemdesc;
 163     $taxname{$taxname} ||= [];
 164     push @{ $taxname{$taxname} }, $taxline;
 165   }
 166
 167   # keys are taxnums
 168   # values are (cumulative) amounts
 169   my %tax_amount;
 170
 171   my $link_table = $self->info->{link_table};
 172
 173   # Preconstruct cust_bill_pkg objects that will become the "final"
 174   # taxlines for each name, so that we can reference them.
 175   # (keys are taxnames)
 176   my %real_taxline_named = map {
 177     $_ => FS::cust_bill_pkg->new({
 178         'pkgnum'    => 0,
 179         'recur'     => 0,
 180         'sdate'     => '',
 181         'edate'     => '',
 182         'itemdesc'  => $_
 183     })
 184   } keys %taxname;
 185
 186   # For each distinct tax name (the values set as $taxline->itemdesc),
 187   # create a consolidated tax item with the total amount and all the links
 188   # of all tax items that share that name.
 189   foreach my $taxname ( keys %taxname ) {
 190     my @tax_links;
 191     my $tax_cust_bill_pkg = $real_taxline_named{$taxname};
 192     $tax_cust_bill_pkg->set( $link_table => \@tax_links );
 193
 194     my $tax_total = 0;
 195     warn "adding $taxname\n" if $DEBUG > 1;
 196
 197     foreach my $taxitem ( @{ $taxname{$taxname} } ) {
 198       # then we need to transfer the amount and the links from the
 199       # line item to the new one we're creating.
 200       $tax_total += $taxitem->setup;
 201       foreach my $link ( @{ $taxitem->get($link_table) } ) {
 202         $link->set('tax_cust_bill_pkg', $tax_cust_bill_pkg);
 203
 204         # if the link represents tax on tax, also fix its taxable pointer
 205         # to point to the "final" taxline
 206         my $taxable_cust_bill_pkg = $link->get('taxable_cust_bill_pkg');
 207         if (my $other_taxname = $taxable_cust_bill_pkg->itemdesc) {
 208           $link->set('taxable_cust_bill_pkg',
 209             $real_taxline_named{$other_taxname}
 210           );
 211         }
 212
 213         push @tax_links, $link;
 214       }
 215     } # foreach $taxitem
 216     next unless $tax_total;
 217
 218     # we should really neverround this up...I guess it's okay if taxline
 219     # already returns amounts with 2 decimal places
 220     $tax_total = sprintf('%.2f', $tax_total );
 221     $tax_cust_bill_pkg->set('setup', $tax_total);
 222
 223     my $pkg_category = qsearchs( 'pkg_category', { 'categoryname' => $taxname,
 224                                                    'disabled'     => '',
 225                                                  },
 226                                );
 227
 228     my @display = ();
 229     if ( $pkg_category and
 230          $conf->config('invoice_latexsummary') ||
 231          $conf->config('invoice_htmlsummary')
 232        )
 233     {
 234       my %hash = (  'section' => $pkg_category->categoryname );
 235       push @display, new FS::cust_bill_pkg_display { type => 'S', %hash };
 236     }
 237     $tax_cust_bill_pkg->set('display', \@display);
 238
 239     push @tax_line_items, $tax_cust_bill_pkg;
 240   }
 241
 242   @tax_line_items;
 243 }
 244
 245 =head1 CLASS METHODS
 246
 247 =item cust_tax_locations LOCATION
 248
 249 Given an L<FS::cust_location> object (or a hash of location fields),
 250 returns a list of all tax jurisdiction locations that could possibly
 251 match it.  This is meant for interactive use: the location editing UI
 252 displays the candidate locations to the user so they can choose the
 253 best match.
 254
 255 =cut
 256
 257 sub cust_tax_locations {
 258   ();
 259 } # shouldn't even get called unless info->{manual_tax_location} is true
 260
 261 =item add_taxproduct DESCRIPTION
 262
 263 If the module allows manually adding tax products (categories of taxable
 264 items/services), this method will be called to do it. (If not, the UI in
 265 browse/part_pkg_taxproduct/* should prevent adding an unlisted tax product.
 266 That is the default behavior, so by default this method simply fails.)
 267
 268 DESCRIPTION is the contents of the taxproduct_description form input, which
 269 will normally be filled in by browse/part_pkg_taxproduct/*.
 270
 271 Must return the newly inserted part_pkg_taxproduct object on success, or
 272 a string on failure.
 273
 274 =cut
 275
 276 sub add_taxproduct {
 277   my $class = shift;
 278   "$class does not allow manually adding taxproducts";
 279 }
 280
 281 =item transfer_batch (batch-style only)
 282
 283 Submits the pending transaction batch for processing, receives the
 284 results, and appends the calculated taxes to all invoices that were
 285 included in the batch.  Then clears their pending flags, and queues
 286 a job to run C<FS::cust_main::Billing::collect> on each affected
 287 customer.
 288
 289 =back
 290
 291 =cut
 292
 293 1;