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

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)