better documentation for UIA's API needs, RT#76831

[freeside.git] / FS / FS / API.pm

diff --git a/FS/FS/API.pm b/FS/FS/API.pm
index fd3793d..6e09713 100644 (file)
--- a/FS/FS/API.pm
+++ b/FS/FS/API.pm
@@ -16,7 +16,20 @@ FS::API - Freeside backend API
 
 =head1 SYNOPSIS
 
-  use FS::API;
+  use Frontier::Client;
+  use Data::Dumper;
+
+  my $url = new URI 'http://localhost:8008/'; #or if accessing remotely, secure
+                                              # the traffic
+
+  my $xmlrpc = new Frontier::Client url=>$url;
+
+  my $result = $xmlrpc->call( 'FS.API.customer_info',
+                                'secret'  => 'sharingiscaring',
+                                'custnum' => 181318,
+                            );
+
+  print Dumper($result);
 
 =head1 DESCRIPTION
 
@@ -525,6 +538,23 @@ sub update_customer {
 Returns general customer information. Takes a list of keys and values as
 parameters with the following keys: custnum, secret 
 
+Example:
+
+  use Frontier::Client;
+  use Data::Dumper;
+
+  my $url = new URI 'http://localhost:8008/'; #or if accessing remotely, secure
+                                              # the traffic
+
+  my $xmlrpc = new Frontier::Client url=>$url;
+
+  my $result = $xmlrpc->call( 'FS.API.customer_info',
+                                'secret'  => 'sharingiscaring',
+                                'custnum' => 181318,
+                            );
+
+  print Dumper($result);
+
 =cut
 
 sub customer_info {
@@ -542,6 +572,28 @@ sub customer_info {
 Returns customer service information.  Takes a list of keys and values as
 parameters with the following keys: custnum, secret
 
+Example:
+
+  use Frontier::Client;
+  use Data::Dumper;
+
+  my $url = new URI 'http://localhost:8008/'; #or if accessing remotely, secure
+                                              # the traffic
+
+  my $xmlrpc = new Frontier::Client url=>$url;
+
+  my $result = $xmlrpc->call( 'FS.API.customer_list_svcs',
+                                'secret'  => 'sharingiscaring',
+                                'custnum' => 181318,
+                            );
+
+  print Dumper($result);
+
+  foreach my $cust_svc ( @{ $result->{'cust_svc'} } ) {
+    #print $cust_svc->{mac_addr}."\n" if exists $cust_svc->{mac_addr};
+    print $cust_svc->{circuit_id}."\n" if exists $cust_svc->{circuit_id};
+  }
+
 =cut
 
 sub customer_list_svcs {
@@ -719,7 +771,205 @@ sub bill_now {
 }
 
 
-#next.. Advertising sources?
+#next.. Delete Advertising sources?
+
+=item list_advertising_sources OPTION => VALUE, ...
+
+Lists all advertising sources.
+
+=over
+
+=item secret
+
+API Secret
+
+=back
+
+Example:
+
+  my $result = FS::API->list_advertising_sources(
+    'secret'  => 'sharingiscaring',
+  );
+
+  if ( $result->{'error'} ) {
+    die $result->{'error'};
+  } else {
+    # list advertising sources returns an array of hashes for sources.
+    print Dumper($result->{'sources'});
+  }
+
+=cut
+
+#list_advertising_sources
+sub list_advertising_sources {
+  my( $class, %opt ) = @_;
+  return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+  my @sources = qsearch('part_referral', {}, '', "")
+    or return { 'error' => 'No referrals' };
+
+  my $return = {
+    'sources'       => [ map $_->hashref, @sources ],
+  };
+
+  $return;
+}
+
+=item add_advertising_source OPTION => VALUE, ...
+
+Add a new advertising source.
+
+=over
+
+=item secret
+
+API Secret
+
+=item referral
+
+Referral name
+
+=item disabled
+
+Referral disabled, Y for disabled or nothing for enabled
+
+=item agentnum
+
+Agent ID number
+
+=item title
+
+External referral ID
+
+=back
+
+Example:
+
+  my $result = FS::API->add_advertising_source(
+    'secret'     => 'sharingiscaring',
+    'referral'   => 'test referral',
+
+    #optional
+    'disabled'   => 'Y',
+    'agentnum'   => '2', #agent id number
+    'title'      => 'test title',
+  );
+
+  if ( $result->{'error'} ) {
+    die $result->{'error'};
+  } else {
+    # add_advertising_source returns new source upon success.
+    print Dumper($result);
+  }
+
+=cut
+
+#add_advertising_source
+sub add_advertising_source {
+  my( $class, %opt ) = @_;
+  return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+  use FS::part_referral;
+
+  my $new_source = $opt{source};
+
+  my $source = new FS::part_referral $new_source;
+
+  my $error = $source->insert;
+
+  my $return = {$source->hash};
+  $return = { 'error' => $error, } if $error;
+
+  $return;
+}
+
+=item edit_advertising_source OPTION => VALUE, ...
+
+Edit a advertising source.
+
+=over
+
+=item secret
+
+API Secret
+
+=item refnum
+
+Referral number to edit
+
+=item source
+
+hash of edited source fields.
+
+=over
+
+=item referral
+
+Referral name
+
+=item disabled
+
+Referral disabled, Y for disabled or nothing for enabled
+
+=item agentnum
+
+Agent ID number
+
+=item title
+
+External referral ID
+
+=back
+
+=back
+
+Example:
+
+  my $result = FS::API->edit_advertising_source(
+    'secret'     => 'sharingiscaring',
+    'refnum'     => '4', # referral number to edit
+    'source'     => {
+       #optional
+       'referral'   => 'test referral',
+       'disabled'   => 'Y',
+       'agentnum'   => '2', #agent id number
+       'title'      => 'test title',
+    }
+  );
+
+  if ( $result->{'error'} ) {
+    die $result->{'error'};
+  } else {
+    # edit_advertising_source returns updated source upon success.
+    print Dumper($result);
+  }
+
+=cut
+
+#edit_advertising_source
+sub edit_advertising_source {
+  my( $class, %opt ) = @_;
+  return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+  use FS::part_referral;
+
+  my $refnum = $opt{refnum};
+  my $source = $opt{source};
+
+  my $old = FS::Record::qsearchs('part_referral', {'refnum' => $refnum,});
+  my $new = new FS::part_referral { $old->hash };
+
+  foreach my $key (keys %$source) {
+    $new->$key($source->{$key});
+  }
+
+  my $error = $new->replace;
+
+  my $return = {$new->hash};
+  $return = { 'error' => $error, } if $error;
+
+  $return;
+}
 
 
 ##