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))
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
 

Revision as of 05:24, 10 February 2015