FS/FS/TaxEngine/suretax.pm

   1 package FS::TaxEngine::suretax;
   2
   3 use strict;
   4 use base 'FS::TaxEngine';
   5 use FS::Conf;
   6 use FS::Record qw(qsearch qsearchs dbh);
   7 use JSON;
   8 use XML::Simple qw(XMLin);
   9 use LWP::UserAgent;
  10 use HTTP::Request::Common;
  11 use DateTime;
  12
  13 our $DEBUG = 1; # prints progress messages
  14 #   $DEBUG = 2; # prints decoded request and response (noisy, be careful)
  15 #   $DEBUG = 3; # prints raw response from the API, ridiculously unreadable
  16
  17 our $json = JSON->new->pretty(1);
  18
  19 our %taxproduct_cache;
  20
  21 our $conf;
  22
  23 FS::UID->install_callback( sub {
  24     $conf = FS::Conf->new;
  25     # should we enable conf caching here?
  26 });
  27
  28 # Tax Situs Rules, for determining tax jurisdiction.
  29 # (may need to be configurable)
  30
  31 # For PSTN calls, use Rule 01, two-out-of-three using NPA-NXX. (The "three"
  32 # are source number, destination number, and charged party number.)
  33 our $TSR_CALL_NPANXX = '01';
  34
  35 # For other types of calls (on-network hosted PBX, SIP-addressed calls,
  36 # other things that don't have an NPA-NXX number), use Rule 11. (See below.)
  37 our $TSR_CALL_OTHER = '11';
  38
  39 # For regular recurring or one-time charges, use Rule 11. This uses the
  40 # service zip code for transaction types that are known to require it, and
  41 # the billing zip code for all other transaction types.
  42 our $TSR_GENERAL = '11';
  43
  44 # XXX incomplete; doesn't handle international taxes (Rule 14) or point
  45 # to point private lines (Rule 07).
  46
  47 our %REGCODE = ( # can be selected per agent
  48   ''          => '99',
  49   'ILEC'      => '00',
  50   'IXC'       => '01',
  51   'CLEC'      => '02',
  52   'VOIP'      => '03',
  53   'ISP'       => '04',
  54   'Wireless'  => '05',
  55 );
  56
  57 sub info {
  58   { batch => 0,
  59     override => 0,
  60   }
  61 }
  62
  63 sub add_sale { } # nothing to do here
  64
  65 sub build_request {
  66   my ($self, %opt) = @_;
  67
  68   my $cust_bill = $self->{cust_bill};
  69   my $cust_main = $cust_bill->cust_main;
  70   my $agentnum = $cust_main->agentnum;
  71   my $date = DateTime->from_epoch(epoch => $cust_bill->_date);
  72
  73   # remember some things that are linked to the customer
  74   $self->{taxstatus} = $cust_main->taxstatus
  75     or die "Customer #".$cust_main->custnum." has no tax status defined.\n";
  76
  77   ($self->{bill_zip}, $self->{bill_plus4}) =
  78     split('-', $cust_main->bill_location->zip);
  79
  80   $self->{regcode} = $REGCODE{ $conf->config('suretax-regulatory_code') };
  81
  82   %taxproduct_cache = ();
  83
  84   # assemble invoice line items
  85   my @lines = map { $self->build_item($_) }
  86               $cust_bill->cust_bill_pkg;
  87
  88   my $ClientNumber = $conf->config('suretax-client_number')
  89     or die "suretax-client_number config required.\n";
  90   my $ValidationKey = $conf->config('suretax-validation_key')
  91     or die "suretax-validation_key config required.\n";
  92   my $BusinessUnit = $conf->config('suretax-business_unit', $agentnum) || '';
  93
  94   return {
  95     ClientNumber  => $ClientNumber,
  96     ValidationKey => $ValidationKey,
  97     BusinessUnit  => $BusinessUnit,
  98     DataYear      => '2015', #$date->year,
  99     DataMonth     => '04', #sprintf('%02d', $date->month),
 100     TotalRevenue  => sprintf('%.4f', $cust_bill->charged),
 101     ReturnFileCode    => ($self->{estimate} ? 'Q' : '0'),
 102     ClientTracking  => $cust_bill->invnum,
 103     IndustryExemption => '',
 104     ResponseGroup => '13',
 105     ResponseType  => 'D2',
 106     STAN          => '',
 107     ItemList      => \@lines,
 108   };
 109 }
 110
 111 =item build_item CUST_BILL_PKG
 112
 113 Takes a sale item and returns any number of request element hashrefs
 114 corresponding to it. Yes, any number, because in a rated usage line item
 115 we have to send each usage detail separately.
 116
 117 =cut
 118
 119 sub build_item {
 120   my $self = shift;
 121   my $cust_bill_pkg = shift;
 122   my $cust_bill = $cust_bill_pkg->cust_bill;
 123   my $billpkgnum = $cust_bill_pkg->billpkgnum;
 124   my $invnum = $cust_bill->invnum;
 125   my $custnum = $cust_bill->custnum;
 126
 127   # get the part_pkg/fee for this line item, and the relevant part of the
 128   # taxproduct cache
 129   my $part_item = $cust_bill_pkg->part_X;
 130   my $taxproduct_of_class = do {
 131     my $part_id = $part_item->table . '#' . $part_item->get($part_item->primary_key);
 132     $taxproduct_cache{$part_id} ||= {};
 133   };
 134
 135   my @items;
 136   my $recur_without_usage = $cust_bill_pkg->recur;
 137
 138   my $location = $cust_bill_pkg->tax_location;
 139   my ($svc_zip, $svc_plus4) = split('-', $location->zip);
 140
 141   my $startdate =
 142     DateTime->from_epoch( epoch => $cust_bill->_date )->strftime('%m-%d-%Y');
 143
 144   my %base_item = (
 145     'LineNumber'      => '',
 146     'InvoiceNumber'   => $billpkgnum,
 147     'CustomerNumber'  => $custnum,
 148     'OrigNumber'      => '',
 149     'TermNumber'      => '',
 150     'BillToNumber'    => '',
 151     'Zipcode'         => $self->{bill_zip},
 152     'Plus4'           => ($self->{bill_plus4} ||= '0000'),
 153     'P2PZipcode'      => $svc_zip,
 154     'P2PPlus4'        => ($svc_plus4 ||= '0000'),
 155     # we don't support Order Placement/Approval zip codes
 156     'Geocode'         => '',
 157     'TransDate'       => $startdate,
 158     'Revenue'         => '',
 159     'Units'           => 0,
 160     'UnitType'        => '00', # "number of unique lines", the only choice
 161     'Seconds'         => 0,
 162     'TaxIncludedCode' => '0',
 163     'TaxSitusRule'    => '',
 164     'TransTypeCode'   => '',
 165     'SalesTypeCode'   => $self->{taxstatus},
 166     'RegulatoryCode'  => $self->{regcode},
 167     'TaxExemptionCodeList' => [ ],
 168     'AuxRevenue'      => 0, # we don't currently support freight and such
 169     'AuxRevenueType'  => '',
 170   );
 171
 172   # some naming conventions:
 173   # 'C#####' is a call detail record (using the acctid)
 174   # 'S#####' is a cust_bill_pkg setup element (using the billpkgnum)
 175   # 'R#####' is a cust_bill_pkg recur element
 176   # always set "InvoiceNumber" = the billpkgnum, so we can link it properly
 177
 178   # cursor all this stuff; data sets can be LARGE
 179   # (if it gets really out of hand, we can also incrementally write JSON
 180   # to a file)
 181
 182   my $details = FS::Cursor->new('cust_bill_pkg_detail', {
 183       billpkgnum  => $cust_bill_pkg->billpkgnum,
 184       amount      => { op => '>', value => 0 }
 185   }, dbh() );
 186   while ( my $cust_bill_pkg_detail = $details->fetch ) {
 187
 188     # look up the tax product for this class
 189     my $classnum = $cust_bill_pkg_detail->classnum;
 190     my $taxproduct = $taxproduct_of_class->{ $classnum } ||= do {
 191       my $part_pkg_taxproduct = $part_item->taxproduct($classnum);
 192       $part_pkg_taxproduct ? $part_pkg_taxproduct->taxproduct : '';
 193     };
 194     die "no taxproduct configured for pkgpart ".$part_item->pkgpart.
 195         ", usage class $classnum\n"
 196         if !$taxproduct;
 197
 198     my $cdrs = FS::Cursor->new('cdr', {
 199         detailnum       => $cust_bill_pkg_detail->detailnum,
 200         freesidestatus  => 'done',
 201     }, dbh() );
 202     while ( my $cdr = $cdrs->fetch ) {
 203       my $calldate =
 204         DateTime->from_epoch( epoch => $cdr->startdate )->strftime('%m-%d-%Y');
 205       # determine the tax situs rule; it's different (probably more accurate)
 206       # if the call has PSTN phone numbers at both ends
 207       my $tsr = $TSR_CALL_OTHER;
 208       if ( $cdr->charged_party =~ /^\d{10}$/ and
 209            $cdr->src           =~ /^\d{10}$/ and
 210            $cdr->dst           =~ /^\d{10}$/ ) {
 211         $tsr = $TSR_CALL_NPANXX;
 212       }
 213       my %hash = (
 214         %base_item,
 215         'LineNumber'      => 'C' . $cdr->acctid,
 216         'OrigNumber'      => $cdr->src,
 217         'TermNumber'      => $cdr->dst,
 218         'BillToNumber'    => $cdr->charged_party,
 219         'TransDate'       => $calldate,
 220         'Revenue'         => $cdr->rated_price, # 4 decimal places
 221         'Units'           => 0, # right?
 222         'CallDuration'    => $cdr->duration,
 223         'TaxSitusRule'    => $tsr,
 224         'TransTypeCode'   => $taxproduct,
 225       );
 226       push @items, \%hash;
 227
 228     } # while ($cdrs->fetch)
 229
 230     # decrement the recurring charge
 231     $recur_without_usage -= $cust_bill_pkg_detail->amount;
 232
 233   } # while ($details->fetch)
 234
 235   # recurring charge
 236   if ( $recur_without_usage > 0 ) {
 237     my $taxproduct = $taxproduct_of_class->{ 'recur' } ||= do {
 238       my $part_pkg_taxproduct = $part_item->taxproduct('recur');
 239       $part_pkg_taxproduct ? $part_pkg_taxproduct->taxproduct : '';
 240     };
 241     die "no taxproduct configured for pkgpart ".$part_item->pkgpart.
 242         " recurring charge\n"
 243         if !$taxproduct;
 244
 245     my $tsr = $TSR_GENERAL;
 246     my %hash = (
 247       %base_item,
 248       'LineNumber'      => 'R' . $billpkgnum,
 249       'Revenue'         => $recur_without_usage, # 4 decimal places
 250       'Units'           => $cust_bill_pkg->units,
 251       'TaxSitusRule'    => $tsr,
 252       'TransTypeCode'   => $taxproduct,
 253     );
 254     # API expects all these fields to be _present_, even when they're not
 255     # required
 256     $hash{$_} = '' foreach(qw(OrigNumber TermNumber BillToNumber));
 257     push @items, \%hash;
 258   }
 259
 260   if ( $cust_bill_pkg->setup > 0 ) {
 261     my $startdate =
 262       DateTime->from_epoch( epoch => $cust_bill->_date )->strftime('%m-%d-%Y');
 263     my $taxproduct = $taxproduct_of_class->{ 'setup' } ||= do {
 264       my $part_pkg_taxproduct = $part_item->taxproduct('setup');
 265       $part_pkg_taxproduct ? $part_pkg_taxproduct->taxproduct : '';
 266     };
 267     die "no taxproduct configured for pkgpart ".$part_item->pkgpart.
 268         " setup charge\n"
 269         if !$taxproduct;
 270
 271     my $tsr = $TSR_GENERAL;
 272     my %hash = (
 273       %base_item,
 274       'LineNumber'      => 'S' . $billpkgnum,
 275       'Revenue'         => $cust_bill_pkg->setup, # 4 decimal places
 276       'Units'           => $cust_bill_pkg->units,
 277       'TaxSitusRule'    => $tsr,
 278       'TransTypeCode'   => $taxproduct,
 279     );
 280     push @items, \%hash;
 281   }
 282
 283   @items;
 284 }
 285
 286 sub make_taxlines {
 287   my $self = shift;
 288
 289   my @elements;
 290
 291   my $cust_bill = shift;
 292   if (!$cust_bill->invnum) {
 293     die "FS::TaxEngine::suretax can't calculate taxes on a non-inserted invoice\n";
 294   }
 295   $self->{cust_bill} = $cust_bill;
 296   my $cust_main = $cust_bill->cust_main;
 297   my $country = $cust_main->bill_location->country;
 298
 299   my $invnum = $cust_bill->invnum;
 300   if (FS::cust_bill_pkg->count("invnum = $invnum") == 0) {
 301     # don't even bother making the request
 302     # (why are we even here, then? invoices with no line items
 303     # should not be created)
 304     return;
 305   }
 306
 307   # assemble the request hash
 308   my $request = $self->build_request;
 309
 310   warn "sending SureTax request\n" if $DEBUG;
 311   my $request_json = $json->encode($request);
 312   warn $request_json if $DEBUG > 1;
 313
 314   my $host = $conf->config('suretax-hostname');
 315   $host ||= 'testapi.taxrating.net';
 316
 317   # We are targeting the "V05" interface:
 318   # - accepts both telecom and general sales transactions
 319   # - produces results broken down by "invoice" (Freeside line item)
 320   my $ua = LWP::UserAgent->new;
 321   my $http_response =  $ua->request(
 322    POST "https://$host/Services/V05/SureTax.asmx/PostRequest",
 323     [ request => $request_json ],
 324     'Content-Type'  => 'application/x-www-form-urlencoded',
 325     'Accept'        => 'application/json',
 326   );
 327
 328   my $raw_response = $http_response->content;
 329   warn "received response\n" if $DEBUG;
 330   warn $raw_response if $DEBUG > 2;
 331   my $response;
 332   if ( $raw_response =~ /^<\?xml/ ) {
 333     # an error message wrapped in a riddle inside an enigma inside an XML
 334     # document...
 335     $response = XMLin( $raw_response );
 336     $raw_response = $response->{content};
 337   }
 338   $response = eval { $json->decode($raw_response) }
 339     or die "$raw_response\n";
 340
 341   # documentation implies this might be necessary
 342   $response = $response->{'d'} if exists $response->{'d'};
 343
 344   warn $json->encode($response) if $DEBUG > 1;
 345
 346   if ( $response->{Successful} ne 'Y' ) {
 347     die $response->{HeaderMessage}."\n";
 348   } else {
 349     my $error = join("\n",
 350       map { $_->{"LineNumber"}.': '. $_->{Message} }
 351       @{ $response->{ItemMessages} }
 352     );
 353     die "$error\n" if $error;
 354   }
 355
 356   return if !$response->{GroupList};
 357   foreach my $taxable ( @{ $response->{GroupList} } ) {
 358     # each member of this array here corresponds to what SureTax calls an
 359     # "invoice" and we call a "line item". The invoice number is
 360     # cust_bill_pkg.billpkgnum.
 361
 362     my ($state, $geocode) = split(/\|/, $taxable->{StateCode});
 363     foreach my $tax_element ( @{ $taxable->{TaxList} } ) {
 364       # create a tax rate location if there isn't one yet
 365       my $taxname = $tax_element->{TaxTypeDesc};
 366       my $taxauth = substr($tax_element->{TaxTypeCode}, 0, 1);
 367       my $tax_rate = FS::tax_rate->new({
 368           data_vendor   => 'suretax',
 369           taxname       => $taxname,
 370           taxclassnum   => '',
 371           taxauth       => $taxauth, # federal / state / city / district
 372           geocode       => $geocode, # this is going to disambiguate all
 373                                      # the taxes named "STATE SALES TAX", etc.
 374           tax           => 0,
 375           fee           => 0,
 376       });
 377       my $error = $tax_rate->find_or_insert;
 378       die "error inserting tax_rate record for '$taxname': $error\n"
 379         if $error;
 380       $tax_rate = $tax_rate->replace_old;
 381
 382       my $tax_rate_location = FS::tax_rate_location->new({
 383           data_vendor => 'suretax',
 384           geocode     => $geocode,
 385           state       => $state,
 386           country     => $country,
 387       });
 388       $error = $tax_rate_location->find_or_insert;
 389       die "error inserting tax_rate_location record for '$geocode': $error\n"
 390         if $error;
 391       $tax_rate_location = $tax_rate_location->replace_old;
 392
 393       push @elements, FS::cust_bill_pkg_tax_rate_location->new({
 394           taxable_billpkgnum  => $taxable->{InvoiceNumber},
 395           taxnum              => $tax_rate->taxnum,
 396           taxtype             => 'FS::tax_rate',
 397           taxratelocationnum  => $tax_rate_location->taxratelocationnum,
 398           amount              => sprintf('%.2f', $tax_element->{TaxAmount}),
 399       });
 400     }
 401   }
 402   return @elements;
 403 }
 404
 405 sub add_taxproduct {
 406   my $class = shift;
 407   my $desc = shift; # tax code and description, separated by a space.
 408   if ($desc =~ s/^(\d{6}+) //) {
 409     my $part_pkg_taxproduct = FS::part_pkg_taxproduct->new({
 410         'data_vendor' => 'suretax',
 411         'taxproduct'  => $1,
 412         'description' => $desc,
 413     });
 414     # $obj_or_error
 415     return $part_pkg_taxproduct->insert || $part_pkg_taxproduct;
 416   } else {
 417     return "illegal suretax tax code '$desc'";
 418   }
 419 }
 420
 421 1;