4 use vars qw( @ISA $DEBUG $me
5 %tax_unittypes %tax_maxtypes %tax_basetypes %tax_authorities
8 use Storable qw( thaw );
10 use FS::Record qw( qsearch qsearchs dbh );
12 use FS::cust_bill_pkg;
13 use FS::cust_tax_location;
14 use FS::part_pkg_taxrate;
16 use FS::Misc qw( csv_from_fixed );
18 @ISA = qw( FS::Record );
21 $me = '[FS::tax_rate]';
25 FS::tax_rate - Object methods for tax_rate objects
31 $record = new FS::tax_rate \%hash;
32 $record = new FS::tax_rate { 'column' => 'value' };
34 $error = $record->insert;
36 $error = $new_record->replace($old_record);
38 $error = $record->delete;
40 $error = $record->check;
44 An FS::tax_rate object represents a tax rate, defined by locale.
45 FS::tax_rate inherits from FS::Record. The following fields are
52 primary key (assigned automatically for new tax rates)
56 a geographic location code provided by a tax data vendor
64 a location code provided by a tax authority
68 a foreign key into FS::tax_class - the type of tax
69 referenced but FS::part_pkg_taxrate
72 the time after which the tax applies
80 second bracket percentage
84 the amount to which the tax applies (first bracket)
88 a cap on the amount of tax if a cap exists
92 percentage on out of jurisdiction purchases
96 second bracket percentage on out of jurisdiction purchases
100 one of the values in %tax_unittypes
104 amount of tax per unit
108 second bracket amount of tax per unit
112 the number of units to which the fee applies (first bracket)
116 the most units to which fees apply (first and second brackets)
120 a value from %tax_maxtypes indicating how brackets accumulate (i.e. monthly, per invoice, etc)
124 if defined, printed on invoices instead of "Tax"
128 a value from %tax_authorities
132 a value from %tax_basetypes indicating the tax basis
136 a value from %tax_passtypes indicating how the tax should displayed to the customer
140 'Y', 'N', or blank indicating the tax can be passed to the customer
144 if 'Y', this tax does not apply to setup fees
148 if 'Y', this tax does not apply to recurring fees
152 if 'Y', has been manually edited
162 Creates a new tax rate. To add the tax rate to the database, see L<"insert">.
166 sub table { 'tax_rate'; }
170 Adds this tax rate to the database. If there is an error, returns the error,
171 otherwise returns false.
175 Deletes this tax rate from the database. If there is an error, returns the
176 error, otherwise returns false.
178 =item replace OLD_RECORD
180 Replaces the OLD_RECORD with this one in the database. If there is an error,
181 returns the error, otherwise returns false.
185 Checks all fields to make sure this is a valid tax rate. If there is an error,
186 returns the error, otherwise returns false. Called by the insert and replace
194 foreach (qw( taxbase taxmax )) {
195 $self->$_(0) unless $self->$_;
198 $self->ut_numbern('taxnum')
199 || $self->ut_text('geocode')
200 || $self->ut_textn('data_vendor')
201 || $self->ut_textn('location')
202 || $self->ut_foreign_key('taxclassnum', 'tax_class', 'taxclassnum')
203 || $self->ut_snumbern('effective_date')
204 || $self->ut_float('tax')
205 || $self->ut_floatn('excessrate')
206 || $self->ut_money('taxbase')
207 || $self->ut_money('taxmax')
208 || $self->ut_floatn('usetax')
209 || $self->ut_floatn('useexcessrate')
210 || $self->ut_numbern('unittype')
211 || $self->ut_floatn('fee')
212 || $self->ut_floatn('excessfee')
213 || $self->ut_floatn('feemax')
214 || $self->ut_numbern('maxtype')
215 || $self->ut_textn('taxname')
216 || $self->ut_numbern('taxauth')
217 || $self->ut_numbern('basetype')
218 || $self->ut_numbern('passtype')
219 || $self->ut_enum('passflag', [ '', 'Y', 'N' ])
220 || $self->ut_enum('setuptax', [ '', 'Y' ] )
221 || $self->ut_enum('recurtax', [ '', 'Y' ] )
222 || $self->ut_enum('manual', [ '', 'Y' ] )
223 || $self->ut_enum('disabled', [ '', 'Y' ] )
224 || $self->SUPER::check
229 =item taxclass_description
231 Returns the human understandable value associated with the related
236 sub taxclass_description {
238 my $tax_class = qsearchs('tax_class', {'taxclassnum' => $self->taxclassnum });
239 $tax_class ? $tax_class->description : '';
244 Returns the human understandable value associated with the unittype column
248 %tax_unittypes = ( '0' => 'access line',
255 $tax_unittypes{$self->unittype};
260 Returns the human understandable value associated with the maxtype column
264 %tax_maxtypes = ( '0' => 'receipts per invoice',
265 '1' => 'receipts per item',
266 '2' => 'total utility charges per utility tax year',
267 '3' => 'total charges per utility tax year',
268 '4' => 'receipts per access line',
269 '9' => 'monthly receipts per location',
274 $tax_maxtypes{$self->maxtype};
279 Returns the human understandable value associated with the basetype column
283 %tax_basetypes = ( '0' => 'sale price',
284 '1' => 'gross receipts',
285 '2' => 'sales taxable telecom revenue',
286 '3' => 'minutes carried',
287 '4' => 'minutes billed',
288 '5' => 'gross operating revenue',
289 '6' => 'access line',
291 '8' => 'gross revenue',
292 '9' => 'portion gross receipts attributable to interstate service',
293 '10' => 'access line',
294 '11' => 'gross profits',
295 '12' => 'tariff rate',
301 $tax_basetypes{$self->basetype};
306 Returns the human understandable value associated with the taxauth column
310 %tax_authorities = ( '0' => 'federal',
315 '5' => 'county administered by state',
316 '6' => 'city administered by state',
317 '7' => 'city administered by county',
318 '8' => 'local administered by state',
319 '9' => 'local administered by county',
324 $tax_authorities{$self->taxauth};
329 Returns the human understandable value associated with the passtype column
333 %tax_passtypes = ( '0' => 'separate tax line',
334 '1' => 'separate surcharge line',
335 '2' => 'surcharge not separated',
336 '3' => 'included in base rate',
341 $tax_passtypes{$self->passtype};
344 =item taxline CUST_BILL_PKG|AMOUNT, ...
346 Returns a listref of a name and an amount of tax calculated for the list
347 of packages/amounts. If an error occurs, a message is returned as a scalar.
354 my $name = $self->taxname;
355 $name = 'Other surcharges'
356 if ($self->passtype == 2);
359 return [$name, $amount] # we always know how to handle disabled taxes
362 my $taxable_charged = 0;
363 my @cust_bill_pkg = grep { $taxable_charged += $_ unless ref; ref; } @_;
365 warn "calculating taxes for ". $self->taxnum. " on ".
366 join (",", map { $_->pkgnum } @cust_bill_pkg)
369 if ($self->passflag eq 'N') {
370 return "fatal: can't (yet) handle taxes not passed to the customer";
373 if ($self->maxtype != 0 && $self->maxtype != 9) {
374 return qq!fatal: can't (yet) handle tax with "!. $self->maxtype_name.
378 if ($self->maxtype == 9) {
379 return qq!fatal: can't (yet) handle tax with "!. $self->maxtype_name.
380 '" threshold'; # "texas" tax
383 if ($self->basetype != 0 && $self->basetype != 1 &&
384 $self->basetype != 6 && $self->basetype != 7 &&
385 $self->basetype != 14
387 return qq!fatal: can't (yet) handle tax with "!. $self->basetype_name.
391 unless ($self->setuptax =~ /^Y$/i) {
392 $taxable_charged += $_->setup foreach @cust_bill_pkg;
394 unless ($self->recurtax =~ /^Y$/i) {
395 $taxable_charged += $_->recur foreach @cust_bill_pkg;
398 my $taxable_units = 0;
399 unless ($self->recurtax =~ /^Y$/i) {
400 if ($self->unittype == 0) {
402 foreach (@cust_bill_pkg) {
403 $taxable_units += $_->units
404 unless $seen{$_->pkgnum};
407 }elsif ($self->unittype == 1) {
408 return qq!fatal: can't (yet) handle fee with minute unit type!;
409 }elsif ($self->unittype == 2) {
412 return qq!fatal: can't (yet) handle unknown unit type in tax!.
418 # XXX insert exemption handling here
420 # the tax or fee is applied to taxbase or feebase and then
421 # the excessrate or excess fee is applied to taxmax or feemax
424 $amount += $taxable_charged * $self->tax;
425 $amount += $taxable_units * $self->fee;
427 warn "calculated taxes as [ $name, $amount ]\n"
430 return [$name, $amount];
434 =item tax_on_tax CUST_MAIN
436 Returns a list of taxes which are candidates for taxing taxes for the
437 given customer (see L<FS::cust_main>)
443 my $cust_main = shift;
445 warn "looking up taxes on tax ". $self->taxnum. " for customer ".
449 my $geocode = $cust_main->geocode($self->data_vendor);
453 my $extra_sql = ' AND ('.
454 join(' OR ', map{ 'geocode = '. $dbh->quote(substr($geocode, 0, $_)) }
459 my $order_by = 'ORDER BY taxclassnum, length(geocode) desc';
460 my $select = 'DISTINCT ON(taxclassnum) *';
462 # should qsearch preface columns with the table to facilitate joins?
463 my @taxclassnums = map { $_->taxclassnum }
464 qsearch( { 'table' => 'part_pkg_taxrate',
466 'hashref' => { 'data_vendor' => $self->data_vendor,
467 'taxclassnumtaxed' => $self->taxclassnum,
469 'extra_sql' => $extra_sql,
470 'order_by' => $order_by,
473 return () unless @taxclassnums;
476 "AND (". join(' OR ', map { "taxclassnum = $_" } @taxclassnums ). ")";
478 qsearch({ 'table' => 'tax_rate',
479 'hashref' => { 'geocode' => $geocode, },
480 'extra_sql' => $extra_sql,
496 my ($param, $job) = @_;
498 my $fh = $param->{filehandle};
499 my $format = $param->{'format'};
507 my @column_lengths = ();
508 my @column_callbacks = ();
509 if ( $format eq 'cch-fixed' || $format eq 'cch-fixed-update' ) {
510 $format =~ s/-fixed//;
511 my $date_format = sub { my $r='';
512 /^(\d{4})(\d{2})(\d{2})$/ && ($r="$1/$2/$3");
515 $column_callbacks[8] = $date_format;
516 push @column_lengths, qw( 10 1 1 8 8 5 8 8 8 1 2 2 30 8 8 10 2 8 2 1 2 2 );
517 push @column_lengths, 1 if $format eq 'cch-update';
521 my ( $count, $last, $min_sec ) = (0, time, 5); #progressbar
522 if ( $job || scalar(@column_callbacks) ) {
524 csv_from_fixed(\$fh, \$count, \@column_lengths, \@column_callbacks);
525 return $error if $error;
529 if ( $format eq 'cch' || $format eq 'cch-update' ) {
530 @fields = qw( geocode inoutcity inoutlocal tax location taxbase taxmax
531 excessrate effective_date taxauth taxtype taxcat taxname
532 usetax useexcessrate fee unittype feemax maxtype passflag
534 push @fields, 'actionflag' if $format eq 'cch-update';
539 $hash->{'actionflag'} ='I' if ($hash->{'data_vendor'} eq 'cch');
540 $hash->{'data_vendor'} ='cch';
541 $hash->{'effective_date'} = str2time($hash->{'effective_date'});
544 join(':', map{ $hash->{$_} } qw(taxtype taxcat) );
546 my %tax_class = ( 'data_vendor' => 'cch',
547 'taxclass' => $taxclassid,
550 my $tax_class = qsearchs( 'tax_class', \%tax_class );
551 return "Error updating tax rate: no tax class $taxclassid"
554 $hash->{'taxclassnum'} = $tax_class->taxclassnum;
556 foreach (qw( inoutcity inoutlocal taxtype taxcat )) {
560 my %passflagmap = ( '0' => '',
564 $hash->{'passflag'} = $passflagmap{$hash->{'passflag'}}
565 if exists $passflagmap{$hash->{'passflag'}};
567 foreach (keys %$hash) {
568 $hash->{$_} = substr($hash->{$_}, 0, 80)
569 if length($hash->{$_}) > 80;
572 my $actionflag = delete($hash->{'actionflag'});
573 if ($actionflag eq 'I') {
574 $insert{ $hash->{'geocode'}. ':'. $hash->{'taxclassnum'} } = $hash;
575 }elsif ($actionflag eq 'D') {
576 $delete{ $hash->{'geocode'}. ':'. $hash->{'taxclassnum'} } = $hash;
578 return "Unexpected action flag: ". $hash->{'actionflag'};
585 } elsif ( $format eq 'extended' ) {
586 die "unimplemented\n";
590 die "unknown format $format";
593 eval "use Text::CSV_XS;";
596 my $csv = new Text::CSV_XS;
600 local $SIG{HUP} = 'IGNORE';
601 local $SIG{INT} = 'IGNORE';
602 local $SIG{QUIT} = 'IGNORE';
603 local $SIG{TERM} = 'IGNORE';
604 local $SIG{TSTP} = 'IGNORE';
605 local $SIG{PIPE} = 'IGNORE';
607 my $oldAutoCommit = $FS::UID::AutoCommit;
608 local $FS::UID::AutoCommit = 0;
611 while ( defined($line=<$fh>) ) {
612 $csv->parse($line) or do {
613 $dbh->rollback if $oldAutoCommit;
614 return "can't parse: ". $csv->error_input();
617 if ( $job ) { # progress bar
618 if ( time - $min_sec > $last ) {
619 my $error = $job->update_statustext(
620 int( 100 * $imported / $count )
622 die $error if $error;
627 my @columns = $csv->fields();
629 my %tax_rate = ( 'data_vendor' => $format );
630 foreach my $field ( @fields ) {
631 $tax_rate{$field} = shift @columns;
633 if ( scalar( @columns ) ) {
634 $dbh->rollback if $oldAutoCommit;
635 return "Unexpected trailing columns in line (wrong format?): $line";
638 my $error = &{$hook}(\%tax_rate);
640 $dbh->rollback if $oldAutoCommit;
648 for (grep { !exists($delete{$_}) } keys %insert) {
649 if ( $job ) { # progress bar
650 if ( time - $min_sec > $last ) {
651 my $error = $job->update_statustext(
652 int( 100 * $imported / $count )
654 die $error if $error;
659 my $tax_rate = new FS::tax_rate( $insert{$_} );
660 my $error = $tax_rate->insert;
663 $dbh->rollback if $oldAutoCommit;
664 my $hashref = $insert{$_};
665 $line = join(", ", map { "$_ => ". $hashref->{$_} } keys(%$hashref) );
666 return "can't insert tax_rate for $line: $error";
672 for (grep { exists($delete{$_}) } keys %insert) {
673 if ( $job ) { # progress bar
674 if ( time - $min_sec > $last ) {
675 my $error = $job->update_statustext(
676 int( 100 * $imported / $count )
678 die $error if $error;
683 my $old = qsearchs( 'tax_rate', $delete{$_} );
685 $dbh->rollback if $oldAutoCommit;
687 return "can't find tax_rate to replace for: ".
688 #join(" ", map { "$_ => ". $old->{$_} } @fields);
689 join(" ", map { "$_ => ". $old->{$_} } keys(%$old) );
691 my $new = new FS::tax_rate({ $old->hash, %{$insert{$_}}, 'manual' => '' });
692 $new->taxnum($old->taxnum);
693 my $error = $new->replace($old);
696 $dbh->rollback if $oldAutoCommit;
697 my $hashref = $insert{$_};
698 $line = join(", ", map { "$_ => ". $hashref->{$_} } keys(%$hashref) );
699 return "can't replace tax_rate for $line: $error";
706 for (grep { !exists($insert{$_}) } keys %delete) {
707 if ( $job ) { # progress bar
708 if ( time - $min_sec > $last ) {
709 my $error = $job->update_statustext(
710 int( 100 * $imported / $count )
712 die $error if $error;
717 my $tax_rate = qsearchs( 'tax_rate', $delete{$_} );
719 $dbh->rollback if $oldAutoCommit;
720 $tax_rate = $delete{$_};
721 return "can't find tax_rate to delete for: ".
722 #join(" ", map { "$_ => ". $tax_rate->{$_} } @fields);
723 join(" ", map { "$_ => ". $tax_rate->{$_} } keys(%$tax_rate) );
725 my $error = $tax_rate->delete;
728 $dbh->rollback if $oldAutoCommit;
729 my $hashref = $delete{$_};
730 $line = join(", ", map { "$_ => ". $hashref->{$_} } keys(%$hashref) );
731 return "can't delete tax_rate for $line: $error";
737 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
739 return "Empty file!" unless ($imported || $format eq 'cch-update');
747 Load a batch import as a queued JSRPC job
754 my $param = thaw(decode_base64(shift));
755 my $format = $param->{'format'}; #well... this is all cch specific
757 my $files = $param->{'uploaded_files'}
758 or die "No files provided.";
760 my (%files) = map { /^(\w+):([\.\w]+)$/ ? ($1,$2):() } split /,/, $files;
762 if ($format eq 'cch' || $format eq 'cch-fixed') {
764 my $oldAutoCommit = $FS::UID::AutoCommit;
765 local $FS::UID::AutoCommit = 0;
769 my @list = ( 'CODE', 'codefile', \&FS::tax_class::batch_import,
770 'PLUS4', 'plus4file', \&FS::cust_tax_location::batch_import,
771 'TXMATRIX', 'txmatrix', \&FS::part_pkg_taxrate::batch_import,
772 'DETAIL', 'detail', \&FS::tax_rate::batch_import,
774 while( scalar(@list) ) {
775 my ($name, $file, $import_sub) = (shift @list, shift @list, shift @list);
776 unless ($files{$file}) {
777 $error = "No $name supplied";
780 my $dir = '%%%FREESIDE_CACHE%%%/cache.'. $FS::UID::datasrc;
781 my $filename = "$dir/". $files{$file};
782 open my $fh, "< $filename" or $error ||= "Can't open $name file: $!";
784 $error ||= &{$import_sub}({ 'filehandle' => $fh, 'format' => $format }, $job);
786 unlink $filename or warn "Can't delete $filename: $!";
790 $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
793 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
796 }elsif ($format eq 'cch-update' || $format eq 'cch-fixed-update') {
798 my $oldAutoCommit = $FS::UID::AutoCommit;
799 local $FS::UID::AutoCommit = 0;
802 my @insert_list = ();
803 my @delete_list = ();
805 my @list = ( 'CODE', 'codefile', \&FS::tax_class::batch_import,
806 'PLUS4', 'plus4file', \&FS::cust_tax_location::batch_import,
807 'TXMATRIX', 'txmatrix', \&FS::part_pkg_taxrate::batch_import,
809 my $dir = '%%%FREESIDE_CACHE%%%/cache.'. $FS::UID::datasrc;
810 while( scalar(@list) ) {
811 my ($name, $file, $import_sub) = (shift @list, shift @list, shift @list);
812 unless ($files{$file}) {
813 $error = "No $name supplied";
816 my $filename = "$dir/". $files{$file};
817 open my $fh, "< $filename" or $error ||= "Can't open $name file $filename: $!";
818 unlink $filename or warn "Can't delete $filename: $!";
820 my $ifh = new File::Temp( TEMPLATE => "$name.insert.XXXXXXXX",
823 ) or die "can't open temp file: $!\n";
825 my $dfh = new File::Temp( TEMPLATE => "$name.delete.XXXXXXXX",
828 ) or die "can't open temp file: $!\n";
832 $handle = $ifh if $_ =~ /"I"\s*$/;
833 $handle = $dfh if $_ =~ /"D"\s*$/;
835 $error = "bad input line: $_" unless $handle;
844 push @insert_list, $name, $ifh->filename, $import_sub;
845 unshift @delete_list, $name, $dfh->filename, $import_sub;
848 while( scalar(@insert_list) ) {
849 my ($name, $file, $import_sub) =
850 (shift @insert_list, shift @insert_list, shift @insert_list);
852 open my $fh, "< $file" or $error ||= "Can't open $name file $file: $!";
854 &{$import_sub}({ 'filehandle' => $fh, 'format' => $format }, $job);
856 unlink $file or warn "Can't delete $file: $!";
859 $error ||= "No DETAIL supplied"
860 unless ($files{detail});
861 open my $fh, "< $dir/". $files{detail}
862 or $error ||= "Can't open DETAIL file: $!";
864 &FS::tax_rate::batch_import({ 'filehandle' => $fh, 'format' => $format },
867 unlink "$dir/". $files{detail} or warn "Can't delete $files{detail}: $!"
870 while( scalar(@delete_list) ) {
871 my ($name, $file, $import_sub) =
872 (shift @delete_list, shift @delete_list, shift @delete_list);
874 open my $fh, "< $file" or $error ||= "Can't open $name file $file: $!";
876 &{$import_sub}({ 'filehandle' => $fh, 'format' => $format }, $job);
878 unlink $file or warn "Can't delete $file: $!";
882 $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
885 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
889 die "Unknown format: $format";
894 =item browse_queries PARAMS
896 Returns a list consisting of a hashref suited for use as the argument
897 to qsearch, and sql query string. Each is based on the PARAMS hashref
898 of keys and values which frequently would be passed as C<scalar($cgi->Vars)>
899 from a form. This conveniently creates the query hashref and count_query
900 string required by the browse and search elements. As a side effect,
901 the PARAMS hashref is untainted and keys with unexpected values are removed.
909 'table' => 'tax_rate',
911 'order_by' => 'ORDER BY geocode, taxclassnum',
916 if ( $params->{data_vendor} =~ /^(\w+)$/ ) {
917 $extra_sql .= ' WHERE data_vendor = '. dbh->quote($1);
919 delete $params->{data_vendor};
922 if ( $params->{geocode} =~ /^(\w+)$/ ) {
923 $extra_sql .= ( $extra_sql =~ /WHERE/i ? ' AND ' : ' WHERE ' ).
924 'geocode LIKE '. dbh->quote($1.'%');
926 delete $params->{geocode};
929 if ( $params->{taxclassnum} =~ /^(\d+)$/ &&
930 qsearchs( 'tax_class', {'taxclassnum' => $1} )
933 $extra_sql .= ( $extra_sql =~ /WHERE/i ? ' AND ' : ' WHERE ' ).
934 ' taxclassnum = '. dbh->quote($1)
936 delete $params->{taxclassnun};
940 if ( $params->{tax_type} =~ /^(\d+)$/ );
941 delete $params->{tax_type}
945 if ( $params->{tax_cat} =~ /^(\d+)$/ );
946 delete $params->{tax_cat}
949 my @taxclassnum = ();
950 if ($tax_type || $tax_cat ) {
951 my $compare = "LIKE '". ( $tax_type || "%" ). ":". ( $tax_cat || "%" ). "'";
952 $compare = "= '$tax_type:$tax_cat'" if ($tax_type && $tax_cat);
953 @taxclassnum = map { $_->taxclassnum }
954 qsearch({ 'table' => 'tax_class',
956 'extra_sql' => "WHERE taxclass $compare",
960 $extra_sql .= ( $extra_sql =~ /WHERE/i ? ' AND ' : ' WHERE ' ). '( '.
961 join(' OR ', map { " taxclassnum = $_ " } @taxclassnum ). ' )'
964 unless ($params->{'showdisabled'}) {
965 $extra_sql .= ( $extra_sql =~ /WHERE/i ? ' AND ' : ' WHERE ' ).
966 "( disabled = '' OR disabled IS NULL )";
969 $query->{extra_sql} = $extra_sql;
971 return ($query, "SELECT COUNT(*) FROM tax_rate $extra_sql");
978 Mixing automatic and manual editing works poorly at present.
982 L<FS::Record>, L<FS::cust_main>, L<FS::cust_bill>, schema.html from the base