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 customer_info
 481
 482 Returns general customer information. Takes a list of keys and values as
 483 parameters with the following keys: custnum, secret
 484
 485 =cut
 486
 487 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
 488
 489 use vars qw( @cust_main_editable_fields @location_editable_fields );
 490 @cust_main_editable_fields = qw(
 491   first last company daytime night fax mobile
 492 );
 493 #  locale
 494 #  payby payinfo payname paystart_month paystart_year payissue payip
 495 #  ss paytype paystate stateid stateid_state
 496 @location_editable_fields = qw(
 497   address1 address2 city county state zip country
 498 );
 499
 500 sub customer_info {
 501   my( $class, %opt ) = @_;
 502   my $conf = new FS::Conf;
 503   return { 'error' => 'Incorrect shared secret' }
 504     unless $opt{secret} eq $conf->config('api_shared_secret');
 505
 506   my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
 507     or return { 'error' => 'Unknown custnum' };
 508
 509   my %return = (
 510     'error'           => '',
 511     'display_custnum' => $cust_main->display_custnum,
 512     'name'            => $cust_main->first. ' '. $cust_main->get('last'),
 513     'balance'         => $cust_main->balance,
 514     'status'          => $cust_main->status,
 515     'statuscolor'     => $cust_main->statuscolor,
 516   );
 517
 518   $return{$_} = $cust_main->get($_)
 519     foreach @cust_main_editable_fields;
 520
 521   for (@location_editable_fields) {
 522     $return{$_} = $cust_main->bill_location->get($_)
 523       if $cust_main->bill_locationnum;
 524     $return{'ship_'.$_} = $cust_main->ship_location->get($_)
 525       if $cust_main->ship_locationnum;
 526   }
 527
 528   my @invoicing_list = $cust_main->invoicing_list;
 529   $return{'invoicing_list'} =
 530     join(', ', grep { $_ !~ /^(POST|FAX)$/ } @invoicing_list );
 531   $return{'postal_invoicing'} =
 532     0 < ( grep { $_ eq 'POST' } @invoicing_list );
 533
 534   #generally, the more useful data from the cust_main record the better.
 535   # well, tell me what you want
 536
 537   return \%return;
 538
 539 }
 540
 541
 542 =item location_info
 543
 544 Returns location specific information for the customer. Takes a list of keys
 545 and values as paramters with the following keys: custnum, secret
 546
 547 =cut
 548
 549 #I also monitor for changes to the additional locations that are applied to
 550 # packages, and would like for those to be exportable as well.  basically the
 551 # location data passed with the custnum.
 552
 553 sub location_info {
 554   my( $class, %opt ) = @_;
 555   my $conf = new FS::Conf;
 556   return { 'error' => 'Incorrect shared secret' }
 557     unless $opt{secret} eq $conf->config('api_shared_secret');
 558
 559   my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
 560
 561   my %return = (
 562     'error'           => '',
 563     'locations'       => [ map $_->hashref, @cust_location ],
 564   );
 565
 566   return \%return;
 567 }
 568
 569 =item bill_now OPTION => VALUE, ...
 570
 571 Bills a single customer now, in the same fashion as the "Bill now" link in the
 572 UI.
 573
 574 Returns a hash reference with a single key, 'error'.  If there is an error,
 575 the value contains the error, otherwise it is empty.
 576
 577 =cut
 578
 579 sub bill_now {
 580   my( $class, %opt ) = @_;
 581   my $conf = new FS::Conf;
 582   return { 'error' => 'Incorrect shared secret' }
 583     unless $opt{secret} eq $conf->config('api_shared_secret');
 584
 585   my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
 586     or return { 'error' => 'Unknown custnum' };
 587
 588   my $error = $cust_main->bill_and_collect( 'fatal'      => 'return',
 589                                             'retry'      => 1,
 590                                             'check_freq' =>'1d',
 591                                           );
 592
 593    return { 'error' => $error,
 594           };
 595
 596 }
 597
 598
 599 #Advertising sources?
 600
 601
 602 1;