|
|
| Line 1: |
Line 1: |
| − | ==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.
| |
| − |
| |
| − | 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 exampple, with an SSH tunnel or VPN) rather than accessing it in plaintext.
| |
| − |
| |
| − | ==METHODS==
| |
| − | ; insert_payment
| |
| − | :Adds a new payment to a customers account. Takes a hash reference as parameter 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
| |
| − | :Adds a a credit to a customers account. Takes a hash reference as parameter 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
| |
| − | :Adds a a credit to a customers account. Takes a hash reference as parameter 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
| |
| − | :Creates a new customer. Takes a hash reference as parameter 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
| |
| − | :; payby
| |
| − | ::CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
| |
| − | :; payinfo
| |
| − | ::Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
| |
| − | :; paycvv
| |
| − | ::Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
| |
| − | :; paydate
| |
| − | ::Expiration date for CARD/DCRD
| |
| − | :; payname
| |
| − | ::Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
| |
| − | :; referral_custnum
| |
| − | ::referring customer number
| |
| − | :; agentnum
| |
| − | ::Agent number
| |
| − | :; agent_custid
| |
| − | ::Agent specific customer number
| |
| − | :; referral_custnum
| |
| − | ::Referring customer number
| |
| − | ; customer_info
| |
| − | :Returns general customer information. Takes a hash reference as parameter with the following keys: custnum and API secret
| |
| − | ; location_info
| |
| − | :Returns location specific information for the customer. Takes a hash reference as parameter with the following keys: custnum,secret
| |
