1 package FS::TaxEngine::suretax;
4 use base 'FS::TaxEngine';
6 use FS::Record qw(qsearch qsearchs dbh);
8 use XML::Simple qw(XMLin);
10 use HTTP::Request::Common;
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
17 our $json = JSON->new->pretty(1);
19 our %taxproduct_cache;
23 FS::UID->install_callback( sub {
24 $conf = FS::Conf->new;
25 # should we enable conf caching here?
28 # Tax Situs Rules, for determining tax jurisdiction.
29 # (may need to be configurable)
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';
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';
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';
44 # XXX incomplete; doesn't handle international taxes (Rule 14) or point
45 # to point private lines (Rule 07).
47 our %REGCODE = ( # can be selected per agent
63 sub add_sale { } # nothing to do here
66 my ($self, %opt) = @_;
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);
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";
77 ($self->{bill_zip}, $self->{bill_plus4}) =
78 split('-', $cust_main->bill_location->zip);
80 $self->{regcode} = $REGCODE{ $conf->config('suretax-regulatory_code') };
82 %taxproduct_cache = ();
84 # assemble invoice line items
85 my @lines = map { $self->build_item($_) }
86 $cust_bill->cust_bill_pkg;
90 my $ClientNumber = $conf->config('suretax-client_number')
91 or die "suretax-client_number config required.\n";
92 my $ValidationKey = $conf->config('suretax-validation_key')
93 or die "suretax-validation_key config required.\n";
94 my $BusinessUnit = $conf->config('suretax-business_unit', $agentnum) || '';
97 ClientNumber => $ClientNumber,
98 ValidationKey => $ValidationKey,
99 BusinessUnit => $BusinessUnit,
100 DataYear => '2015', #$date->year,
101 DataMonth => '04', #sprintf('%02d', $date->month),
102 TotalRevenue => sprintf('%.4f', $cust_bill->charged),
103 ReturnFileCode => ($self->{estimate} ? 'Q' : '0'),
104 ClientTracking => $cust_bill->invnum,
105 IndustryExemption => '',
106 ResponseGroup => '13',
107 ResponseType => 'D2',
113 =item build_item CUST_BILL_PKG
115 Takes a sale item and returns any number of request element hashrefs
116 corresponding to it. Yes, any number, because in a rated usage line item
117 we have to send each usage detail separately.
123 my $cust_bill_pkg = shift;
124 my $cust_bill = $cust_bill_pkg->cust_bill;
125 my $billpkgnum = $cust_bill_pkg->billpkgnum;
126 my $invnum = $cust_bill->invnum;
127 my $custnum = $cust_bill->custnum;
129 # get the part_pkg/fee for this line item, and the relevant part of the
131 my $part_item = $cust_bill_pkg->part_X;
132 my $taxproduct_of_class = do {
133 my $part_id = $part_item->table . '#' . $part_item->get($part_item->primary_key);
134 $taxproduct_cache{$part_id} ||= {};
138 my $recur_without_usage = $cust_bill_pkg->recur;
140 my $location = $cust_bill_pkg->tax_location;
141 my ($svc_zip, $svc_plus4) = split('-', $location->zip);
144 DateTime->from_epoch( epoch => $cust_bill->_date )->strftime('%m-%d-%Y');
148 'InvoiceNumber' => $billpkgnum,
149 'CustomerNumber' => $custnum,
152 'BillToNumber' => '',
153 'Zipcode' => $self->{bill_zip},
154 'Plus4' => ($self->{bill_plus4} ||= '0000'),
155 'P2PZipcode' => $svc_zip,
156 'P2PPlus4' => ($svc_plus4 ||= '0000'),
157 # we don't support Order Placement/Approval zip codes
159 'TransDate' => $startdate,
162 'UnitType' => '00', # "number of unique lines", the only choice
164 'TaxIncludedCode' => '0',
165 'TaxSitusRule' => '',
166 'TransTypeCode' => '',
167 'SalesTypeCode' => $self->{taxstatus},
168 'RegulatoryCode' => $self->{regcode},
169 'TaxExemptionCodeList' => [ ],
170 'AuxRevenue' => 0, # we don't currently support freight and such
171 'AuxRevenueType' => '',
174 # some naming conventions:
175 # 'C#####' is a call detail record (using the acctid)
176 # 'S#####' is a cust_bill_pkg setup element (using the billpkgnum)
177 # 'R#####' is a cust_bill_pkg recur element
178 # always set "InvoiceNumber" = the billpkgnum, so we can link it properly
180 # cursor all this stuff; data sets can be LARGE
181 # (if it gets really out of hand, we can also incrementally write JSON
184 my $details = FS::Cursor->new('cust_bill_pkg_detail', {
185 billpkgnum => $cust_bill_pkg->billpkgnum,
186 amount => { op => '>', value => 0 }
188 while ( my $cust_bill_pkg_detail = $details->fetch ) {
190 # look up the tax product for this class
191 my $classnum = $cust_bill_pkg_detail->classnum;
192 my $taxproduct = $taxproduct_of_class->{ $classnum } ||= do {
193 my $part_pkg_taxproduct = $part_item->taxproduct($classnum);
194 $part_pkg_taxproduct ? $part_pkg_taxproduct->taxproduct : '';
196 die "no taxproduct configured for pkgpart ".$part_item->pkgpart.
197 ", usage class $classnum\n"
200 my $cdrs = FS::Cursor->new('cdr', {
201 detailnum => $cust_bill_pkg_detail->detailnum,
202 freesidestatus => 'done',
204 while ( my $cdr = $cdrs->fetch ) {
206 DateTime->from_epoch( epoch => $cdr->startdate )->strftime('%m-%d-%Y');
207 # determine the tax situs rule; it's different (probably more accurate)
208 # if the call has PSTN phone numbers at both ends
209 my $tsr = $TSR_CALL_OTHER;
210 if ( $cdr->charged_party =~ /^\d{10}$/ and
211 $cdr->src =~ /^\d{10}$/ and
212 $cdr->dst =~ /^\d{10}$/ ) {
213 $tsr = $TSR_CALL_NPANXX;
217 'LineNumber' => 'C' . $cdr->acctid,
218 'OrigNumber' => $cdr->src,
219 'TermNumber' => $cdr->dst,
220 'BillToNumber' => $cdr->charged_party,
221 'TransDate' => $calldate,
222 'Revenue' => $cdr->rated_price, # 4 decimal places
223 'Units' => 0, # right?
224 'CallDuration' => $cdr->duration,
225 'TaxSitusRule' => $tsr,
226 'TransTypeCode' => $taxproduct,
230 } # while ($cdrs->fetch)
232 # decrement the recurring charge
233 $recur_without_usage -= $cust_bill_pkg_detail->amount;
235 } # while ($details->fetch)
238 if ( $recur_without_usage > 0 ) {
239 my $taxproduct = $taxproduct_of_class->{ 'recur' } ||= do {
240 my $part_pkg_taxproduct = $part_item->taxproduct('recur');
241 $part_pkg_taxproduct ? $part_pkg_taxproduct->taxproduct : '';
243 die "no taxproduct configured for pkgpart ".$part_item->pkgpart.
244 " recurring charge\n"
247 my $tsr = $TSR_GENERAL;
250 'LineNumber' => 'R' . $billpkgnum,
251 'Revenue' => $recur_without_usage, # 4 decimal places
252 'Units' => $cust_bill_pkg->units,
253 'TaxSitusRule' => $tsr,
254 'TransTypeCode' => $taxproduct,
256 # API expects all these fields to be _present_, even when they're not
258 $hash{$_} = '' foreach(qw(OrigNumber TermNumber BillToNumber));
262 if ( $cust_bill_pkg->setup > 0 ) {
264 DateTime->from_epoch( epoch => $cust_bill->_date )->strftime('%m-%d-%Y');
265 my $taxproduct = $taxproduct_of_class->{ 'setup' } ||= do {
266 my $part_pkg_taxproduct = $part_item->taxproduct('setup');
267 $part_pkg_taxproduct ? $part_pkg_taxproduct->taxproduct : '';
269 die "no taxproduct configured for pkgpart ".$part_item->pkgpart.
273 my $tsr = $TSR_GENERAL;
276 'LineNumber' => 'S' . $billpkgnum,
277 'Revenue' => $cust_bill_pkg->setup, # 4 decimal places
278 'Units' => $cust_bill_pkg->units,
279 'TaxSitusRule' => $tsr,
280 'TransTypeCode' => $taxproduct,
293 my $cust_bill = shift;
294 if (!$cust_bill->invnum) {
295 die "FS::TaxEngine::suretax can't calculate taxes on a non-inserted invoice\n";
297 $self->{cust_bill} = $cust_bill;
298 my $cust_main = $cust_bill->cust_main;
299 my $country = $cust_main->bill_location->country;
301 my $invnum = $cust_bill->invnum;
302 if (FS::cust_bill_pkg->count("invnum = $invnum") == 0) {
303 # don't even bother making the request
304 # (why are we even here, then? invoices with no line items
305 # should not be created)
309 # assemble the request hash
310 my $request = $self->build_request;
312 warn "no taxable items in invoice; skipping SureTax request\n" if $DEBUG;
316 warn "sending SureTax request\n" if $DEBUG;
317 my $request_json = $json->encode($request);
318 warn $request_json if $DEBUG > 1;
320 my $host = $conf->config('suretax-hostname');
321 $host ||= 'testapi.taxrating.net';
323 # We are targeting the "V05" interface:
324 # - accepts both telecom and general sales transactions
325 # - produces results broken down by "invoice" (Freeside line item)
326 my $ua = LWP::UserAgent->new;
327 my $http_response = $ua->request(
328 POST "https://$host/Services/V05/SureTax.asmx/PostRequest",
329 [ request => $request_json ],
330 'Content-Type' => 'application/x-www-form-urlencoded',
331 'Accept' => 'application/json',
334 my $raw_response = $http_response->content;
335 warn "received response\n" if $DEBUG;
336 warn $raw_response if $DEBUG > 2;
338 if ( $raw_response =~ /^<\?xml/ ) {
339 # an error message wrapped in a riddle inside an enigma inside an XML
341 $response = XMLin( $raw_response );
342 $raw_response = $response->{content};
344 $response = eval { $json->decode($raw_response) }
345 or die "$raw_response\n";
347 # documentation implies this might be necessary
348 $response = $response->{'d'} if exists $response->{'d'};
350 warn $json->encode($response) if $DEBUG > 1;
352 if ( $response->{Successful} ne 'Y' ) {
353 die $response->{HeaderMessage}."\n";
355 my $error = join("\n",
356 map { $_->{"LineNumber"}.': '. $_->{Message} }
357 @{ $response->{ItemMessages} }
359 die "$error\n" if $error;
362 return if !$response->{GroupList};
363 foreach my $taxable ( @{ $response->{GroupList} } ) {
364 # each member of this array here corresponds to what SureTax calls an
365 # "invoice" and we call a "line item". The invoice number is
366 # cust_bill_pkg.billpkgnum.
368 my ($state, $geocode) = split(/\|/, $taxable->{StateCode});
369 foreach my $tax_element ( @{ $taxable->{TaxList} } ) {
370 # create a tax rate location if there isn't one yet
371 my $taxname = $tax_element->{TaxTypeDesc};
372 my $taxauth = substr($tax_element->{TaxTypeCode}, 0, 1);
373 my $tax_rate = FS::tax_rate->new({
374 data_vendor => 'suretax',
377 taxauth => $taxauth, # federal / state / city / district
378 geocode => $geocode, # this is going to disambiguate all
379 # the taxes named "STATE SALES TAX", etc.
383 my $error = $tax_rate->find_or_insert;
384 die "error inserting tax_rate record for '$taxname': $error\n"
386 $tax_rate = $tax_rate->replace_old;
388 my $tax_rate_location = FS::tax_rate_location->new({
389 data_vendor => 'suretax',
394 $error = $tax_rate_location->find_or_insert;
395 die "error inserting tax_rate_location record for '$geocode': $error\n"
397 $tax_rate_location = $tax_rate_location->replace_old;
399 push @elements, FS::cust_bill_pkg_tax_rate_location->new({
400 taxable_billpkgnum => $taxable->{InvoiceNumber},
401 taxnum => $tax_rate->taxnum,
402 taxtype => 'FS::tax_rate',
403 taxratelocationnum => $tax_rate_location->taxratelocationnum,
404 amount => sprintf('%.2f', $tax_element->{TaxAmount}),
413 my $desc = shift; # tax code and description, separated by a space.
414 if ($desc =~ s/^(\d{6}+) //) {
415 my $part_pkg_taxproduct = FS::part_pkg_taxproduct->new({
416 'data_vendor' => 'suretax',
418 'description' => $desc,
421 return $part_pkg_taxproduct->insert || $part_pkg_taxproduct;
423 return "illegal suretax tax code '$desc'";