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;
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) || '';
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',
111 =item build_item CUST_BILL_PKG
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.
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;
127 # get the part_pkg/fee for this line item, and the relevant part of the
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} ||= {};
136 my $recur_without_usage = $cust_bill_pkg->recur;
138 my $location = $cust_bill_pkg->tax_location;
139 my ($svc_zip, $svc_plus4) = split('-', $location->zip);
142 DateTime->from_epoch( epoch => $cust_bill->_date )->strftime('%m-%d-%Y');
146 'InvoiceNumber' => $billpkgnum,
147 'CustomerNumber' => $custnum,
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
157 'TransDate' => $startdate,
160 'UnitType' => '00', # "number of unique lines", the only choice
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' => '',
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
178 # cursor all this stuff; data sets can be LARGE
179 # (if it gets really out of hand, we can also incrementally write JSON
182 my $details = FS::Cursor->new('cust_bill_pkg_detail', {
183 billpkgnum => $cust_bill_pkg->billpkgnum,
184 amount => { op => '>', value => 0 }
186 while ( my $cust_bill_pkg_detail = $details->fetch ) {
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 : '';
194 die "no taxproduct configured for pkgpart ".$part_item->pkgpart.
195 ", usage class $classnum\n"
198 my $cdrs = FS::Cursor->new('cdr', {
199 detailnum => $cust_bill_pkg_detail->detailnum,
200 freesidestatus => 'done',
202 while ( my $cdr = $cdrs->fetch ) {
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;
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,
228 } # while ($cdrs->fetch)
230 # decrement the recurring charge
231 $recur_without_usage -= $cust_bill_pkg_detail->amount;
233 } # while ($details->fetch)
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 : '';
241 die "no taxproduct configured for pkgpart ".$part_item->pkgpart.
242 " recurring charge\n"
245 my $tsr = $TSR_GENERAL;
248 'LineNumber' => 'R' . $billpkgnum,
249 'Revenue' => $recur_without_usage, # 4 decimal places
250 'Units' => $cust_bill_pkg->units,
251 'TaxSitusRule' => $tsr,
252 'TransTypeCode' => $taxproduct,
254 # API expects all these fields to be _present_, even when they're not
256 $hash{$_} = '' foreach(qw(OrigNumber TermNumber BillToNumber));
260 if ( $cust_bill_pkg->setup > 0 ) {
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 : '';
267 die "no taxproduct configured for pkgpart ".$part_item->pkgpart.
271 my $tsr = $TSR_GENERAL;
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,
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";
295 $self->{cust_bill} = $cust_bill;
296 my $cust_main = $cust_bill->cust_main;
297 my $country = $cust_main->bill_location->country;
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)
307 # assemble the request hash
308 my $request = $self->build_request;
310 warn "sending SureTax request\n" if $DEBUG;
311 my $request_json = $json->encode($request);
312 warn $request_json if $DEBUG > 1;
314 my $host = $conf->config('suretax-hostname');
315 $host ||= 'testapi.taxrating.net';
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',
328 my $raw_response = $http_response->content;
329 warn "received response\n" if $DEBUG;
330 warn $raw_response if $DEBUG > 2;
332 if ( $raw_response =~ /^<\?xml/ ) {
333 # an error message wrapped in a riddle inside an enigma inside an XML
335 $response = XMLin( $raw_response );
336 $raw_response = $response->{content};
338 $response = eval { $json->decode($raw_response) }
339 or die "$raw_response\n";
341 # documentation implies this might be necessary
342 $response = $response->{'d'} if exists $response->{'d'};
344 warn $json->encode($response) if $DEBUG > 1;
346 if ( $response->{Successful} ne 'Y' ) {
347 die $response->{HeaderMessage}."\n";
349 my $error = join("\n",
350 map { $_->{"LineNumber"}.': '. $_->{Message} }
351 @{ $response->{ItemMessages} }
353 die "$error\n" if $error;
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.
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',
371 taxauth => $taxauth, # federal / state / city / district
372 geocode => $geocode, # this is going to disambiguate all
373 # the taxes named "STATE SALES TAX", etc.
377 my $error = $tax_rate->find_or_insert;
378 die "error inserting tax_rate record for '$taxname': $error\n"
380 $tax_rate = $tax_rate->replace_old;
382 my $tax_rate_location = FS::tax_rate_location->new({
383 data_vendor => 'suretax',
388 $error = $tax_rate_location->find_or_insert;
389 die "error inserting tax_rate_location record for '$geocode': $error\n"
391 $tax_rate_location = $tax_rate_location->replace_old;
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}),
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',
412 'description' => $desc,
415 return $part_pkg_taxproduct->insert || $part_pkg_taxproduct;
417 return "illegal suretax tax code '$desc'";