Difference between revisions of "Freeside:3:Documentation:Developer/FS/API"

From Freeside
Jump to: navigation, search
m (Edit via perl MediaWiki framework (1.13))
m (Edit via perl MediaWiki framework (1.13))
 
(7 intermediate revisions by the same user not shown)
Line 9: Line 9:
 
This module implements a backend API for advanced back-office integration.
 
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.
+
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 ccess 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 exampple, with an SSH tunnel or VPN) rather than accessing it in plaintext.
+
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==
 
==METHODS==
; insert_payment
+
; insert_payment OPTION => VALUE, ...
:Adds a new payment to a customers account. Takes a hash reference as parameter with the following keys:
+
:Adds a new payment to a customers account. Takes a list of keys and values as paramters with the following keys:
 
:; secret
 
:; secret
 
::API Secret
 
::API Secret
Line 27: Line 27:
 
::Option date for payment
 
::Option date for payment
  
::Example:
+
:Example:
 
<code>
 
<code>
 
   my $result = FS::API->insert_payment(
 
   my $result = FS::API->insert_payment(
Line 46: Line 46:
 
   }
 
   }
 
</code>
 
</code>
; insert_credit
+
; insert_credit OPTION => VALUE, ...
:Adds a a credit to a customers account. Takes a hash reference as parameter with the following keys
+
:Adds a a credit to a customers account. Takes a list of keys and values as parameters with the following keys
 
:; secret
 
:; secret
 
::API Secret
 
::API Secret
Line 57: Line 57:
 
::The date the credit will be posted
 
::The date the credit will be posted
  
::Example:
+
:Example:
 
<code>
 
<code>
 
   my $result = FS::API->insert_credit(
 
   my $result = FS::API->insert_credit(
Line 75: Line 75:
 
   }
 
   }
 
</code>
 
</code>
; insert_refund
+
; insert_refund OPTION => VALUE, ...
:Adds a a credit to a customers account. Takes a hash reference as parameter with the following keys: custnum,payby,refund
+
: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:
 
:Example:
Line 97: Line 97:
 
   }
 
   }
 
</code>
 
</code>
; new_customer
+
; new_customer OPTION => VALUE, ...
:Creates a new customer. Takes a hash reference as parameter with the following keys:
+
:Creates a new customer. Takes a list of keys and values as parameters with the following keys:
 
:; secret
 
:; secret
 
::API Secret
 
::API Secret
Line 152: Line 152:
 
::Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
 
::Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
 
:; referral_custnum
 
:; referral_custnum
::referring customer number
+
::Referring customer number
 +
:; salesnum
 +
::Sales person number
 
:; agentnum
 
:; agentnum
 
::Agent number
 
::Agent number
Line 159: Line 161:
 
:; referral_custnum
 
:; referral_custnum
 
::Referring customer number
 
::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)
 +
:; 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
 +
:; salesnum
 +
::Sales person number
 +
:; agentnum
 +
::Agent number
 
; customer_info
 
; customer_info
:Returns general customer information. Takes a hash reference as parameter with the following keys: custnum and API secret
+
:Returns general customer information. Takes a list of keys and values as parameters with the following keys: custnum, secret
 
; location_info
 
; location_info
:Returns location specific information for the customer. Takes a hash reference as parameter 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
 +
; 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)

Latest revision as of 06:14, 28 September 2015

NAME

FS::API - Freeside backend API

SYNOPSIS

 use FS::API;

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 ccess 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:

 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'};
 }

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:

 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'};
 }

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:

 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'};
 }

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
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
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)
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
salesnum
Sales person number
agentnum
Agent number
customer_info
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)