Jeremyd: Edit via perl MediaWiki framework (1.13)

2015-11-18T15:17:17Z

Edit via perl MediaWiki framework (1.13)

New page

==NAME==
FS::API - Freeside backend API

==SYNOPSIS==
<code>
use FS::API;
</code>
==DESCRIPTION==
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.

==METHODS==
; insert_payment OPTION => VALUE, ...
:Adds a new payment to a customers account. Takes a list of keys and values as paramters with the following keys:
:; secret
::API Secret
:; custnum
::Customer number
:; payby
::Payment type
:; paid
::Amount paid
:; _date
::Option date for payment

:Example:
<code>
my $result = FS::API->insert_payment(
'secret' => 'sharingiscaring',
'custnum' => 181318,
'payby' => 'CASH',
'paid' => '54.32',

#optional
'_date' => 1397977200, #UNIX timestamp
);

if ( $result->{'error'} ) {
die $result->{'error'};
} else {
#payment was inserted
print "paynum ". $result->{'paynum'};
}
</code>
; insert_credit OPTION => VALUE, ...
:Adds a a credit to a customers account. Takes a list of keys and values as parameters with the following keys
:; secret
::API Secret
:; custnum
::customer number
:; amount
::Amount of the credit
:; _date
::The date the credit will be posted

:Example:
<code>
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'};
}
</code>
; insert_refund OPTION => VALUE, ...
: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:
<code>
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'};
}
</code>
; new_customer OPTION => VALUE, ...
:Creates a new customer. Takes a list of keys and values as parameters with the following keys:
:; secret
::API Secret
:; first
::first name (required)
:; last
::last name (required)
:; ss
::(not typically collected; mostly used for ACH transactions)
:; company
::Company name
:; address1 (required)
::Address line one
:; city (required)
::City
:; county
::County
:; state (required)
::State
:; zip (required)
::Zip or postal code
:; country
::2 Digit Country Code
:; latitude
::latitude
:; Longitude
::longitude
:; geocode
::Currently used for third party tax vendor lookups
:; censustract
::Used for determining FCC 477 reporting
:; censusyear
::Used for determining FCC 477 reporting
:; daytime
::Daytime phone number
:; night
::Evening phone number
:; fax
::Fax number
:; mobile
::Mobile number
:; invoicing_list
::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
:; referral_custnum
::Referring customer number
:; salesnum
::Sales person number
:; agentnum
::Agent number
:; agent_custid
::Agent specific customer number
:; referral_custnum
::Referring customer number
; update_customer
: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:
:; secret
::API Secret (required)
:; custnum
::Customer number (required)
:; first
::first name
:; last
::last name
:; company
::Company name
:; address1
::Address line one
:; city
::City
:; county
::County
:; state
::State
:; zip
::Zip or postal code
:; country
::2 Digit Country Code
:; daytime
::Daytime phone number
:; night
::Evening phone number
:; fax
::Fax number
:; mobile
::Mobile number
:; invoicing_list
::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
:; referral_custnum
::Referring customer number
:; salesnum
::Sales person number
:; agentnum
::Agent number
; customer_info OPTION => VALUE, ...
:Returns general customer information. Takes a list of keys and values as parameters with the following keys: custnum, secret
; location_info
:Returns location specific information for the customer. Takes a list of keys and values as paramters with the following keys: custnum, secret
; bill_now OPTION => VALUE, ...
: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:
:; secret
::API Secret (required)
:; custnum
::Customer number (required)

Freeside:4:Documentation:Developer/FS/API - Revision history

Jeremyd: Edit via perl MediaWiki framework (1.13)