FS::API - Freeside backend 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);
This module implements a backend API for advanced back-office integration.
In contrast to the self-service API, which authenticates an end-user and offers functionality to that end user, the backend API performs a simple shared-secret authentication and offers full, administrator functionality, enabling integration with other back-office systems. Only access this API from a secure network from other backoffice machines. DON'T use this API to create customer portal functionality.
If accessing this API remotely with XML-RPC or JSON-RPC, be careful to block the port by default, only allow access from back-office servers with the same security precations as the Freeside server, and encrypt the communication channel (for example, with an SSH tunnel or VPN) rather than accessing it in plaintext.
Adds a new payment to a customers account. Takes a list of keys and values as paramters with the following keys:
API Secret
Customer number
Payment type
Amount paid
Option date for payment
Optional order number
Example:
my $result = FS::API->insert_payment(
'secret' => 'sharingiscaring',
'custnum' => 181318,
'payby' => 'CASH',
'paid' => '54.32',
#optional
'_date' => 1397977200, #UNIX timestamp
'order_number' => '12345',
);
if ( $result->{'error'} ) {
die $result->{'error'};
} else {
#payment was inserted
print "paynum ". $result->{'paynum'};
}
Adds a a credit to a customers account. Takes a list of keys and values as parameters with the following keys
API Secret
customer number
Amount of the credit
The date the credit will be posted
Example:
my $result = FS::API->insert_credit(
'secret' => 'sharingiscaring',
'custnum' => 181318,
'amount' => '54.32',
#optional
'_date' => 1397977200, #UNIX timestamp
);
if ( $result->{'error'} ) {
die $result->{'error'};
} else {
#credit was inserted
print "crednum ". $result->{'crednum'};
}
Applies payments and credits for this customer. Takes a list of keys and values as parameter with the following keys:
Adds a a credit to a customers account. Takes a list of keys and values as parmeters with the following keys: custnum, payby, refund
Example:
my $result = FS::API->insert_refund(
'secret' => 'sharingiscaring',
'custnum' => 181318,
'payby' => 'CASH',
'refund' => '54.32',
#optional
'_date' => 1397977200, #UNIX timestamp
);
if ( $result->{'error'} ) {
die $result->{'error'};
} else {
#refund was inserted
print "refundnum ". $result->{'crednum'};
}
Creates a new customer. Takes a list of keys and values as parameters with the following keys:
API Secret
first name (required)
last name (required)
(not typically collected; mostly used for ACH transactions)
Company name
Address line one
City
County
State
Zip or postal code
2 Digit Country Code
latitude
longitude
Currently used for third party tax vendor lookups
Used for determining FCC 477 reporting
Used for determining FCC 477 reporting
Optional shipping address fields. If sending an optional shipping address, ship_address1, ship_city, ship_state and ship_zip are required.
Daytime phone number
Evening phone number
Fax number
Mobile number
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), postal_invoicing Set to 1 to enable postal invoicing
Referring customer number
Sales person number
Agent number
Agent specific customer number
Referring customer number
Updates an existing customer. Passing an empty value clears that field, while NOT passing that key/value at all leaves it alone. Takes a list of keys and values as parameters with the following keys:
API Secret (required)
Customer number (required)
first name
last name
Company name
Address line one
City
County
State
Zip or postal code
2 Digit Country Code
Daytime phone number
Evening phone number
Fax number
Mobile number
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), postal_invoicing Set to 1 to enable postal invoicing
Referring customer number
Sales person number
Agent number
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);
Returns the following fields:
Empty, or error message (in which case, none of the other fields will be populated)
Optional customer number display override - if present, use this for all UI instead of the real database custnum
Simple string for customer identification (from first, last, company)
Agent (Company)
Sales person
Advertising channel
Customer class
Employee (initial customer insert)
Referring customer
Comma-separated list of email addresses
0 or 1
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};
}
Returns location specific information for the customer. Takes a list of keys and values as paramters with the following keys: custnum, secret
Lists all customer packages.
Example:
my $result = FS::API->list_packages(
'secret' => 'sharingiscaring',
'custnum' => custnum,
);
if ( $result->{'error'} ) {
die $result->{'error'};
} else {
# list packages returns an array of hashes for packages ordered by custnum and pkgnum.
print Dumper($result->{'pkgs'});
}
Get package status.
Example:
my $result = FS::API->package_status(
'secret' => 'sharingiscaring',
'pkgnum' => pkgnum,
);
if ( $result->{'error'} ) {
die $result->{'error'};
} else {
# package status returns a hash with the status for a package.
print Dumper($result->{'status'});
}
Orders a new customer package. Takes a list of keys and values as paramaters with the following keys:
API Secret
Including this implements per-customer custom pricing for this package, overriding package definition pricing
Including this implements per-customer custom pricing for this package, overriding package definition pricing
A single string for just one detail line, or an array reference of one or more lines of detail
Updates package location. Takes a list of keys and values as parameters with the following keys:
pkgnum
secret
locationnum - pass this, or the following keys (don't pass both)
locationname
address1
address2
city
county
state
zip
addr_clean
country
censustract
censusyear
location_type
location_number
location_kind
incorporated
On error, returns a hashref with an 'error' key. On success, returns a hashref with 'pkgnum' and 'locationnum' keys, containing the new values.
Bills a single customer now, in the same fashion as the "Bill now" link in the UI.
Returns a hash reference with a single key, 'error'. If there is an error, the value contains the error, otherwise it is empty. Takes a list of keys and values as parameters with the following keys:
Lists all advertising sources.
API Secret
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'});
}
Add a new advertising source.
API Secret
Referral name
Referral disabled, Y for disabled or nothing for enabled
Agent ID number
External referral ID
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);
}
Edit a advertising source.
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);
}
Each e-mail address, or FS::cust_contact record, has two opt-in flags: message_dest: recieve non-invoicing messages, and invoice_dest: recieve invoicing messages
Use this API call to remove opt-in flags for an e-mail address
E-Mail address
Enabled by default: Set this parameter as 0 in your API call to leave the message_dest flag as is
Enabled by default: Set this parameter as 0 in your API call to leave the invoice_dest flag as is