FS/FS/API.pm

   1 package FS::API;
   2
   3 use FS::Conf;
   4 use FS::Record qw( qsearch qsearchs );
   5 use FS::cust_main;
   6 use FS::cust_location;
   7 use FS::cust_pay;
   8 use FS::cust_credit;
   9 use FS::cust_refund;
  10
  11 =head1 NAME
  12
  13 FS::API - Freeside backend API
  14
  15 =head1 SYNOPSIS
  16
  17   use FS::API;
  18
  19 =head1 DESCRIPTION
  20
  21 This module implements a backend API for advanced back-office integration.
  22
  23 In contrast to the self-service API, which authenticates an end-user and offers
  24 functionality to that end user, the backend API performs a simple shared-secret
  25 authentication and offers full, administrator functionality, enabling
  26 integration with other back-office systems.
  27
  28 If accessing this API remotely with XML-RPC or JSON-RPC, be careful to block
  29 the port by default, only allow access from back-office servers with the same
  30 security precations as the Freeside server, and encrypt the communication
  31 channel (for example, with an SSH tunnel or VPN) rather than accessing it
  32 in plaintext.
  33
  34 =head1 METHODS
  35
  36 =over 4
  37
  38 =item insert_payment OPTION => VALUE, ...
  39
  40 Adds a new payment to a customers account. Takes a list of keys and values as
  41 paramters with the following keys:
  42
  43 =over 5
  44
  45 =item secret
  46
  47 API Secret
  48
  49 =item custnum
  50
  51 Customer number
  52
  53 =item payby
  54
  55 Payment type
  56
  57 =item paid
  58
  59 Amount paid
  60
  61 =item _date
  62
  63 Option date for payment
  64
  65 =back
  66
  67 Example:
  68
  69   my $result = FS::API->insert_payment(
  70     'secret'  => 'sharingiscaring',
  71     'custnum' => 181318,
  72     'payby'   => 'CASH',
  73     'paid'    => '54.32',
  74
  75     #optional
  76     '_date'   => 1397977200, #UNIX timestamp
  77   );
  78
  79   if ( $result->{'error'} ) {
  80     die $result->{'error'};
  81   } else {
  82     #payment was inserted
  83     print "paynum ". $result->{'paynum'};
  84   }
  85
  86 =cut
  87
  88 #enter cash payment
  89 sub insert_payment {
  90   my($class, %opt) = @_;
  91   my $conf = new FS::Conf;
  92   return { 'error' => 'Incorrect shared secret' }
  93     unless $opt{secret} eq $conf->config('api_shared_secret');
  94
  95   #less "raw" than this?  we are the backoffice API, and aren't worried
  96   # about version migration ala cust_main/cust_location here
  97   my $cust_pay = new FS::cust_pay { %opt };
  98   my $error = $cust_pay->insert( 'manual'=>1 );
  99   return { 'error'  => $error,
 100            'paynum' => $cust_pay->paynum,
 101          };
 102 }
 103
 104 # pass the phone number ( from svc_phone )
 105 sub insert_payment_phonenum {
 106   my($class, %opt) = @_;
 107   my $conf = new FS::Conf;
 108   return { 'error' => 'Incorrect shared secret' }
 109     unless $opt{secret} eq $conf->config('api_shared_secret');
 110
 111   $class->_by_phonenum('insert_payment', %opt);
 112
 113 }
 114
 115 sub _by_phonenum {
 116   my($class, $method, %opt) = @_;
 117   my $conf = new FS::Conf;
 118   return { 'error' => 'Incorrect shared secret' }
 119     unless $opt{secret} eq $conf->config('api_shared_secret');
 120
 121   my $phonenum = delete $opt{'phonenum'};
 122
 123   my $svc_phone = qsearchs('svc_phone', { 'phonenum' => $phonenum } )
 124     or return { 'error' => 'Unknown phonenum' };
 125
 126   my $cust_pkg = $svc_phone->cust_svc->cust_pkg
 127     or return { 'error' => 'Unlinked phonenum' };
 128
 129   $opt{'custnum'} = $cust_pkg->custnum;
 130
 131   $class->$method(%opt);
 132
 133 }
 134
 135 =item insert_credit OPTION => VALUE, ...
 136
 137 Adds a a credit to a customers account.  Takes a list of keys and values as
 138 parameters with the following keys
 139
 140 =over
 141
 142 =item secret
 143
 144 API Secret
 145
 146 =item custnum
 147
 148 customer number
 149
 150 =item amount
 151
 152 Amount of the credit
 153
 154 =item _date
 155
 156 The date the credit will be posted
 157
 158 =back
 159
 160 Example:
 161
 162   my $result = FS::API->insert_credit(
 163     'secret'  => 'sharingiscaring',
 164     'custnum' => 181318,
 165     'amount'  => '54.32',
 166
 167     #optional
 168     '_date'   => 1397977200, #UNIX timestamp
 169   );
 170
 171   if ( $result->{'error'} ) {
 172     die $result->{'error'};
 173   } else {
 174     #credit was inserted
 175     print "crednum ". $result->{'crednum'};
 176   }
 177
 178 =cut
 179
 180 #Enter credit
 181 sub insert_credit {
 182   my($class, %opt) = @_;
 183   my $conf = new FS::Conf;
 184   return { 'error' => 'Incorrect shared secret' }
 185     unless $opt{secret} eq $conf->config('api_shared_secret');
 186
 187   $opt{'reasonnum'} ||= $conf->config('api_credit_reason');
 188
 189   #less "raw" than this?  we are the backoffice API, and aren't worried
 190   # about version migration ala cust_main/cust_location here
 191   my $cust_credit = new FS::cust_credit { %opt };
 192   my $error = $cust_credit->insert;
 193   return { 'error'  => $error,
 194            'crednum' => $cust_credit->crednum,
 195          };
 196 }
 197
 198 # pass the phone number ( from svc_phone )
 199 sub insert_credit_phonenum {
 200   my($class, %opt) = @_;
 201   my $conf = new FS::Conf;
 202   return { 'error' => 'Incorrect shared secret' }
 203     unless $opt{secret} eq $conf->config('api_shared_secret');
 204
 205   $class->_by_phonenum('insert_credit', %opt);
 206
 207 }
 208
 209 =item insert_refund OPTION => VALUE, ...
 210
 211 Adds a a credit to a customers account.  Takes a list of keys and values as
 212 parmeters with the following keys: custnum, payby, refund
 213
 214 Example:
 215
 216   my $result = FS::API->insert_refund(
 217     'secret'  => 'sharingiscaring',
 218     'custnum' => 181318,
 219     'payby'   => 'CASH',
 220     'refund'  => '54.32',
 221
 222     #optional
 223     '_date'   => 1397977200, #UNIX timestamp
 224   );
 225
 226   if ( $result->{'error'} ) {
 227     die $result->{'error'};
 228   } else {
 229     #refund was inserted
 230     print "refundnum ". $result->{'crednum'};
 231   }
 232
 233 =cut
 234
 235 #Enter cash refund.
 236 sub insert_refund {
 237   my($class, %opt) = @_;
 238   my $conf = new FS::Conf;
 239   return { 'error' => 'Incorrect shared secret' }
 240     unless $opt{secret} eq $conf->config('api_shared_secret');
 241
 242   # when github pull request #24 is merged,
 243   #  will have to change over to default reasonnum like credit
 244   # but until then, this will do
 245   $opt{'reason'} ||= 'API refund';
 246
 247   #less "raw" than this?  we are the backoffice API, and aren't worried
 248   # about version migration ala cust_main/cust_location here
 249   my $cust_refund = new FS::cust_refund { %opt };
 250   my $error = $cust_refund->insert;
 251   return { 'error'     => $error,
 252            'refundnum' => $cust_refund->refundnum,
 253          };
 254 }
 255
 256 # pass the phone number ( from svc_phone )
 257 sub insert_refund_phonenum {
 258   my($class, %opt) = @_;
 259   my $conf = new FS::Conf;
 260   return { 'error' => 'Incorrect shared secret' }
 261     unless $opt{secret} eq $conf->config('api_shared_secret');
 262
 263   $class->_by_phonenum('insert_refund', %opt);
 264
 265 }
 266
 267 #---
 268
 269 # "2 way syncing" ?  start with non-sync pulling info here, then if necessary
 270 # figure out how to trigger something when those things change
 271
 272 # long-term: package changes?
 273
 274 =item new_customer OPTION => VALUE, ...
 275
 276 Creates a new customer. Takes a list of keys and values as parameters with the
 277 following keys:
 278
 279 =over 4
 280
 281 =item secret
 282
 283 API Secret
 284
 285 =item first
 286
 287 first name (required)
 288
 289 =item last
 290
 291 last name (required)
 292
 293 =item ss
 294
 295 (not typically collected; mostly used for ACH transactions)
 296
 297 =item company
 298
 299 Company name
 300
 301 =item address1 (required)
 302
 303 Address line one
 304
 305 =item city (required)
 306
 307 City
 308
 309 =item county
 310
 311 County
 312
 313 =item state (required)
 314
 315 State
 316
 317 =item zip (required)
 318
 319 Zip or postal code
 320
 321 =item country
 322
 323 2 Digit Country Code
 324
 325 =item latitude
 326
 327 latitude
 328
 329 =item Longitude
 330
 331 longitude
 332
 333 =item geocode
 334
 335 Currently used for third party tax vendor lookups
 336
 337 =item censustract
 338
 339 Used for determining FCC 477 reporting
 340
 341 =item censusyear
 342
 343 Used for determining FCC 477 reporting
 344
 345 =item daytime
 346
 347 Daytime phone number
 348
 349 =item night
 350
 351 Evening phone number
 352
 353 =item fax
 354
 355 Fax number
 356
 357 =item mobile
 358
 359 Mobile number
 360
 361 =item invoicing_list
 362
 363 comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses),
 364 postal_invoicing
 365 Set to 1 to enable postal invoicing
 366
 367 =item payby
 368
 369 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
 370
 371 =item payinfo
 372
 373 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
 374
 375 =item paycvv
 376
 377 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
 378
 379 =item paydate
 380
 381 Expiration date for CARD/DCRD
 382
 383 =item payname
 384
 385 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
 386
 387 =item referral_custnum
 388
 389 Referring customer number
 390
 391 =item salesnum
 392
 393 Sales person number
 394
 395 =item agentnum
 396
 397 Agent number
 398
 399 =item agent_custid
 400
 401 Agent specific customer number
 402
 403 =item referral_custnum
 404
 405 Referring customer number
 406
 407 =back
 408
 409 =cut
 410
 411 #certainly false laziness w/ClientAPI::Signup new_customer/new_customer_minimal
 412 # but approaching this from a clean start / back-office perspective
 413 #  i.e. no package/service, no immediate credit card run, etc.
 414
 415 sub new_customer {
 416   my( $class, %opt ) = @_;
 417   my $conf = new FS::Conf;
 418   return { 'error' => 'Incorrect shared secret' }
 419     unless $opt{secret} eq $conf->config('api_shared_secret');
 420
 421   #default agentnum like signup_server-default_agentnum?
 422
 423   #same for refnum like signup_server-default_refnum
 424
 425   my $cust_main = new FS::cust_main ( {
 426       'agentnum' => $agentnum,
 427       'refnum'   => $opt{refnum}
 428                     || $conf->config('signup_server-default_refnum'),
 429       'payby'    => 'BILL',
 430       'tagnum'   => [ FS::part_tag->default_tags ],
 431
 432       map { $_ => $opt{$_} } qw(
 433         agentnum salesnum refnum agent_custid referral_custnum
 434         last first company
 435         daytime night fax mobile
 436         payby payinfo paydate paycvv payname
 437       ),
 438
 439   } );
 440
 441   my @invoicing_list = $opt{'invoicing_list'}
 442                          ? split( /\s*\,\s*/, $opt{'invoicing_list'} )
 443                          : ();
 444   push @invoicing_list, 'POST' if $opt{'postal_invoicing'};
 445
 446   my ($bill_hash, $ship_hash);
 447   foreach my $f (FS::cust_main->location_fields) {
 448     # avoid having to change this in front-end code
 449     $bill_hash->{$f} = $opt{"bill_$f"} || $opt{$f};
 450     $ship_hash->{$f} = $opt{"ship_$f"};
 451   }
 452
 453   my $bill_location = FS::cust_location->new($bill_hash);
 454   my $ship_location;
 455   # we don't have an equivalent of the "same" checkbox in selfservice^Wthis API
 456   # so is there a ship address, and if so, is it different from the billing
 457   # address?
 458   if ( length($ship_hash->{address1}) > 0 and
 459           grep { $bill_hash->{$_} ne $ship_hash->{$_} } keys(%$ship_hash)
 460          ) {
 461
 462     $ship_location = FS::cust_location->new( $ship_hash );
 463
 464   } else {
 465     $ship_location = $bill_location;
 466   }
 467
 468   $cust_main->set('bill_location' => $bill_location);
 469   $cust_main->set('ship_location' => $ship_location);
 470
 471   $error = $cust_main->insert( {}, \@invoicing_list );
 472   return { 'error'   => $error } if $error;
 473
 474   return { 'error'   => '',
 475            'custnum' => $cust_main->custnum,
 476          };
 477
 478 }
 479
 480 =item update_customer
 481
 482 Updates an existing customer. Passing an empty value clears that field, while
 483 NOT passing that key/value at all leaves it alone. Takes a list of keys and
 484 values as parameters with the following keys:
 485
 486 =over 4
 487
 488 =item secret
 489
 490 API Secret (required)
 491
 492 =item custnum
 493
 494 Customer number (required)
 495
 496 =item first
 497
 498 first name
 499
 500 =item last
 501
 502 last name
 503
 504 =item company
 505
 506 Company name
 507
 508 =item address1
 509
 510 Address line one
 511
 512 =item city
 513
 514 City
 515
 516 =item county
 517
 518 County
 519
 520 =item state
 521
 522 State
 523
 524 =item zip
 525
 526 Zip or postal code
 527
 528 =item country
 529
 530 2 Digit Country Code
 531
 532 =item daytime
 533
 534 Daytime phone number
 535
 536 =item night
 537
 538 Evening phone number
 539
 540 =item fax
 541
 542 Fax number
 543
 544 =item mobile
 545
 546 Mobile number
 547
 548 =item invoicing_list
 549
 550 Comma-separated list of email addresses for email invoices. The special value
 551 'POST' is used to designate postal invoicing (it may be specified alone or in
 552 addition to email addresses)
 553
 554 =item payby
 555
 556 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
 557
 558 =item payinfo
 559
 560 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid
 561 +"pin" for PREPAY, purchase order number for BILL
 562
 563 =item paycvv
 564
 565 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
 566
 567 =item paydate
 568
 569 Expiration date for CARD/DCRD
 570
 571 =item payname
 572
 573 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
 574
 575 =item referral_custnum
 576
 577 Referring customer number
 578
 579 =item salesnum
 580
 581 Sales person number
 582
 583 =item agentnum
 584
 585 Agent number
 586
 587 =back
 588
 589 =cut
 590
 591 sub update_customer {
 592
 593  my( $class, %opt ) = @_;
 594
 595   my $conf = new FS::Conf;
 596
 597
 598   my $custnum = $opt{'custnum'}
 599     or return { 'error' => "no customer record" };
 600
 601   my $cust_main = qsearchs('cust_main', { 'custnum' => $custnum } )
 602     or return { 'error' => "unknown custnum $custnum" };
 603
 604   my $new = new FS::cust_main { $cust_main->hash };
 605
 606   $new->set( $_ => $opt{$_} )
 607     foreach grep { exists $opt{$_} } qw(
 608         agentnum salesnum refnum agent_custid referral_custnum
 609         last first company
 610         daytime night fax mobile
 611         payby payinfo paydate paycvv payname
 612       ),
 613
 614   my @invoicing_list;
 615   if ( exists $opt{'invoicing_list'} || exists $opt{'postal_invoicing'} ) {
 616     @invoicing_list = split( /\s*\,\s*/, $opt{'invoicing_list'} );
 617     push @invoicing_list, 'POST' if $opt{'postal_invoicing'};
 618   } else {
 619     @invoicing_list = $cust_main->invoicing_list;
 620   }
 621
 622   if ( exists( $opt{'address1'} ) ) {
 623     my $bill_location = FS::cust_location->new({
 624         map { $_ => $opt{$_} } @location_editable_fields
 625     });
 626     $bill_location->set('custnum' => $custnum);
 627     my $error = $bill_location->find_or_insert;
 628     die $error if $error;
 629
 630     # if this is unchanged from before, cust_main::replace will ignore it
 631     $new->set('bill_location' => $bill_location);
 632   }
 633
 634   if ( exists($opt{'ship_address1'}) && length($opt{"ship_address1"}) > 0 ) {
 635     my $ship_location = FS::cust_location->new({
 636         map { $_ => $opt{"ship_$_"} } @location_editable_fields
 637     });
 638
 639     $ship_location->set('custnum' => $custnum);
 640     my $error = $ship_location->find_or_insert;
 641     die $error if $error;
 642
 643     $new->set('ship_location' => $ship_location);
 644
 645    } elsif (exists($opt{'ship_address1'} ) && !grep { length($opt{"ship_$_"}) } @location_editable_fields ) {
 646       my $ship_location = $new->bill_location;
 647      $new->set('ship_location' => $ship_location);
 648     }
 649
 650   my $error = $new->replace( $cust_main, \@invoicing_list );
 651   return { 'error'   => $error } if $error;
 652
 653   return { 'error'   => '',
 654          };
 655 }
 656
 657
 658 =item customer_info
 659
 660 Returns general customer information. Takes a list of keys and values as
 661 parameters with the following keys: custnum, secret
 662
 663 =cut
 664
 665 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
 666
 667 use vars qw( @cust_main_editable_fields @location_editable_fields );
 668 @cust_main_editable_fields = qw(
 669   first last company daytime night fax mobile
 670 );
 671 #  locale
 672 #  payby payinfo payname paystart_month paystart_year payissue payip
 673 #  ss paytype paystate stateid stateid_state
 674 @location_editable_fields = qw(
 675   address1 address2 city county state zip country
 676 );
 677
 678 sub customer_info {
 679   my( $class, %opt ) = @_;
 680   my $conf = new FS::Conf;
 681   return { 'error' => 'Incorrect shared secret' }
 682     unless $opt{secret} eq $conf->config('api_shared_secret');
 683
 684   my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
 685     or return { 'error' => 'Unknown custnum' };
 686
 687   my %return = (
 688     'error'           => '',
 689     'display_custnum' => $cust_main->display_custnum,
 690     'name'            => $cust_main->first. ' '. $cust_main->get('last'),
 691     'balance'         => $cust_main->balance,
 692     'status'          => $cust_main->status,
 693     'statuscolor'     => $cust_main->statuscolor,
 694   );
 695
 696   $return{$_} = $cust_main->get($_)
 697     foreach @cust_main_editable_fields;
 698
 699   for (@location_editable_fields) {
 700     $return{$_} = $cust_main->bill_location->get($_)
 701       if $cust_main->bill_locationnum;
 702     $return{'ship_'.$_} = $cust_main->ship_location->get($_)
 703       if $cust_main->ship_locationnum;
 704   }
 705
 706   my @invoicing_list = $cust_main->invoicing_list;
 707   $return{'invoicing_list'} =
 708     join(', ', grep { $_ !~ /^(POST|FAX)$/ } @invoicing_list );
 709   $return{'postal_invoicing'} =
 710     0 < ( grep { $_ eq 'POST' } @invoicing_list );
 711
 712   #generally, the more useful data from the cust_main record the better.
 713   # well, tell me what you want
 714
 715   return \%return;
 716
 717 }
 718
 719
 720 =item location_info
 721
 722 Returns location specific information for the customer. Takes a list of keys
 723 and values as paramters with the following keys: custnum, secret
 724
 725 =cut
 726
 727 #I also monitor for changes to the additional locations that are applied to
 728 # packages, and would like for those to be exportable as well.  basically the
 729 # location data passed with the custnum.
 730
 731 sub location_info {
 732   my( $class, %opt ) = @_;
 733   my $conf = new FS::Conf;
 734   return { 'error' => 'Incorrect shared secret' }
 735     unless $opt{secret} eq $conf->config('api_shared_secret');
 736
 737   my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
 738
 739   my %return = (
 740     'error'           => '',
 741     'locations'       => [ map $_->hashref, @cust_location ],
 742   );
 743
 744   return \%return;
 745 }
 746
 747 =item bill_now OPTION => VALUE, ...
 748
 749 Bills a single customer now, in the same fashion as the "Bill now" link in the
 750 UI.
 751
 752 Returns a hash reference with a single key, 'error'.  If there is an error,
 753 the value contains the error, otherwise it is empty. Takes a list of keys and
 754 values as parameters with the following keys:
 755
 756 =over 4
 757
 758 =item secret
 759
 760 API Secret (required)
 761
 762 =item custnum
 763
 764 Customer number (required)
 765
 766 =back
 767
 768 =cut
 769
 770 sub bill_now {
 771   my( $class, %opt ) = @_;
 772   my $conf = new FS::Conf;
 773   return { 'error' => 'Incorrect shared secret' }
 774     unless $opt{secret} eq $conf->config('api_shared_secret');
 775
 776   my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
 777     or return { 'error' => 'Unknown custnum' };
 778
 779   my $error = $cust_main->bill_and_collect( 'fatal'      => 'return',
 780                                             'retry'      => 1,
 781                                             'check_freq' =>'1d',
 782                                           );
 783
 784    return { 'error' => $error,
 785           };
 786
 787 }
 788
 789
 790 #Advertising sources?
 791
 792
 793 1;