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 Updates an existing customer. Passing an empty value clears that field, while NOT passing that key/value at all leaves it alone.
 482 Takes a hash reference as parameter with the following keys:
 483
 484 =over 4
 485
 486 =item secret
 487
 488 API Secret (required)
 489
 490 =item custnum
 491
 492 Customer number (required)
 493
 494 =item first
 495
 496 first name
 497
 498 =item last
 499
 500 last name
 501
 502 =item company
 503
 504 Company name
 505
 506 =item address1
 507
 508 Address line one
 509
 510 =item city
 511
 512 City
 513
 514 =item county
 515
 516 County
 517
 518 =item state
 519
 520 State
 521
 522 =item zip
 523
 524 Zip or postal code
 525
 526 =item country
 527
 528 2 Digit Country Code
 529
 530 =item daytime
 531
 532 Daytime phone number
 533
 534 =item night
 535
 536 Evening phone number
 537
 538 =item fax
 539
 540 Fax number
 541
 542 =item mobile
 543
 544 Mobile number
 545
 546 =item invoicing_list
 547
 548 comma-separated list of email addresses for email invoices. The special value '$
 549 postal_invoicing
 550 Set to 1 to enable postal invoicing
 551
 552 =item payby
 553
 554 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
 555
 556 =item payinfo
 557
 558 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pi$
 559
 560 =item paycvv
 561
 562 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
 563
 564 =item paydate
 565
 566 Expiration date for CARD/DCRD
 567
 568 =item payname
 569
 570 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
 571
 572 =item referral_custnum
 573
 574 Referring customer number
 575
 576 =item salesnum
 577
 578 Sales person number
 579
 580 =item agentnum
 581
 582 Agent number
 583
 584 =back
 585
 586 =cut
 587
 588 sub update_customer {
 589
 590  my( $class, %opt ) = @_;
 591
 592   my $conf = new FS::Conf;
 593
 594
 595   my $custnum = $opt{'custnum'}
 596     or return { 'error' => "no customer record" };
 597
 598   my $cust_main = qsearchs('cust_main', { 'custnum' => $custnum } )
 599     or return { 'error' => "unknown custnum $custnum" };
 600
 601   my $new = new FS::cust_main { $cust_main->hash };
 602
 603   $new->set( $_ => $opt{$_} )
 604     foreach grep { exists $opt{$_} } qw(
 605         agentnum salesnum refnum agent_custid referral_custnum
 606         last first company
 607         daytime night fax mobile
 608         payby payinfo paydate paycvv payname
 609       ),
 610
 611   my @invoicing_list = $opt{'invoicing_list'}
 612                          ? split( /\s*\,\s*/, $opt{'invoicing_list'} )
 613                          : $cust_main->invoicing_list;
 614   push @invoicing_list, 'POST' if $opt{'postal_invoicing'};
 615
 616   if ( exists( $opt{'address1'} ) ) {
 617     my $bill_location = FS::cust_location->new({
 618         map { $_ => $opt{$_} } @location_editable_fields
 619     });
 620     $bill_location->set('custnum' => $custnum);
 621     my $error = $bill_location->find_or_insert;
 622     die $error if $error;
 623
 624     # if this is unchanged from before, cust_main::replace will ignore it
 625     $new->set('bill_location' => $bill_location);
 626   }
 627
 628   if ( exists($opt{'ship_address1'}) ) {
 629     my $ship_location = FS::cust_location->new({
 630         map { $_ => $opt{"ship_$_"} } @location_editable_fields
 631     });
 632
 633     $ship_location->set('custnum' => $custnum);
 634     my $error = $ship_location->find_or_insert;
 635     die $error if $error;
 636
 637    }
 638
 639    if ( !grep { length($opt{"ship_$_"}) } @location_editable_fields ) {
 640       # Selfservice unfortunately tries to indicate "same as billing
 641       # address" by sending all fields empty.  Did this ever work?
 642
 643       my $ship_location = $cust_main->bill_location;
 644       $new->set('ship_location' => $ship_location);
 645
 646    }
 647   my $error = $new->replace( $cust_main, \@invoicing_list );
 648   return { 'error'   => $error } if $error;
 649
 650   return { 'error'   => '',
 651          };
 652 }
 653
 654
 655 =item customer_info
 656
 657 Returns general customer information. Takes a list of keys and values as
 658 parameters with the following keys: custnum, secret
 659
 660 =cut
 661
 662 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
 663
 664 use vars qw( @cust_main_editable_fields @location_editable_fields );
 665 @cust_main_editable_fields = qw(
 666   first last company daytime night fax mobile
 667 );
 668 #  locale
 669 #  payby payinfo payname paystart_month paystart_year payissue payip
 670 #  ss paytype paystate stateid stateid_state
 671 @location_editable_fields = qw(
 672   address1 address2 city county state zip country
 673 );
 674
 675 sub customer_info {
 676   my( $class, %opt ) = @_;
 677   my $conf = new FS::Conf;
 678   return { 'error' => 'Incorrect shared secret' }
 679     unless $opt{secret} eq $conf->config('api_shared_secret');
 680
 681   my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
 682     or return { 'error' => 'Unknown custnum' };
 683
 684   my %return = (
 685     'error'           => '',
 686     'display_custnum' => $cust_main->display_custnum,
 687     'name'            => $cust_main->first. ' '. $cust_main->get('last'),
 688     'balance'         => $cust_main->balance,
 689     'status'          => $cust_main->status,
 690     'statuscolor'     => $cust_main->statuscolor,
 691   );
 692
 693   $return{$_} = $cust_main->get($_)
 694     foreach @cust_main_editable_fields;
 695
 696   for (@location_editable_fields) {
 697     $return{$_} = $cust_main->bill_location->get($_)
 698       if $cust_main->bill_locationnum;
 699     $return{'ship_'.$_} = $cust_main->ship_location->get($_)
 700       if $cust_main->ship_locationnum;
 701   }
 702
 703   my @invoicing_list = $cust_main->invoicing_list;
 704   $return{'invoicing_list'} =
 705     join(', ', grep { $_ !~ /^(POST|FAX)$/ } @invoicing_list );
 706   $return{'postal_invoicing'} =
 707     0 < ( grep { $_ eq 'POST' } @invoicing_list );
 708
 709   #generally, the more useful data from the cust_main record the better.
 710   # well, tell me what you want
 711
 712   return \%return;
 713
 714 }
 715
 716
 717 =item location_info
 718
 719 Returns location specific information for the customer. Takes a list of keys
 720 and values as paramters with the following keys: custnum, secret
 721
 722 =cut
 723
 724 #I also monitor for changes to the additional locations that are applied to
 725 # packages, and would like for those to be exportable as well.  basically the
 726 # location data passed with the custnum.
 727
 728 sub location_info {
 729   my( $class, %opt ) = @_;
 730   my $conf = new FS::Conf;
 731   return { 'error' => 'Incorrect shared secret' }
 732     unless $opt{secret} eq $conf->config('api_shared_secret');
 733
 734   my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
 735
 736   my %return = (
 737     'error'           => '',
 738     'locations'       => [ map $_->hashref, @cust_location ],
 739   );
 740
 741   return \%return;
 742 }
 743
 744 =item bill_now OPTION => VALUE, ...
 745
 746 Bills a single customer now, in the same fashion as the "Bill now" link in the
 747 UI.
 748
 749 Returns a hash reference with a single key, 'error'.  If there is an error,
 750 the value contains the error, otherwise it is empty.
 751
 752 =cut
 753
 754 sub bill_now {
 755   my( $class, %opt ) = @_;
 756   my $conf = new FS::Conf;
 757   return { 'error' => 'Incorrect shared secret' }
 758     unless $opt{secret} eq $conf->config('api_shared_secret');
 759
 760   my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
 761     or return { 'error' => 'Unknown custnum' };
 762
 763   my $error = $cust_main->bill_and_collect( 'fatal'      => 'return',
 764                                             'retry'      => 1,
 765                                             'check_freq' =>'1d',
 766                                           );
 767
 768    return { 'error' => $error,
 769           };
 770
 771 }
 772
 773
 774 #Advertising sources?
 775
 776
 777 1;