FS::API - Freeside backend API
use FS::API;
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
CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
Expiration date for CARD/DCRD
Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
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)
CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid +"pin" for PREPAY, purchase order number for BILL
Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
Expiration date for CARD/DCRD
Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
Referring customer number
Sales person number
Agent number
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 general customer information. Takes a list of keys and values as parameters with the following keys: custnum, secret
Returns customer service information. Takes a list of keys and values as parameters with the following keys: custnum, secret
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 paramters 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);
}
Hey! The above document had some coding errors, which are explained below:
=over without closing =back
=over without closing =back