Freeside:1.7:Documentation:Developer/FS/SelfService

NAME

FS::SelfService - Freeside self-service API

SYNOPSIS


 # password and shell account changes
 use FS::SelfService qw(passwd chfn chsh);

 # "my account" functionality
 use FS::SelfService qw( login customer_info invoice cancel payment_info process_payment );

 my $rv = login( { 'username' => $username,
                   'domain'   => $domain,
                   'password' => $password,
                 }
               );

 if ( $rv->{'error'} ) {
   #handle login error...
 } else {
   #successful login
   my $session_id = $rv->{'session_id'};
 }

 my $customer_info = customer_info( { 'session_id' => $session_id } );

 #payment_info and process_payment are available in 1.5+ only
 my $payment_info = payment_info( { 'session_id' => $session_id } );

 #!!! process_payment example

 #!!! list_pkgs example

 #!!! order_pkg example

 #!!! cancel_pkg example

 # signup functionality
 use FS::SelfService qw( signup_info new_customer );

 my $signup_info = signup_info;

 $rv = new_customer( {
                       'first'            => $first,
                       'last'             => $last,
                       'company'          => $company,
                       'address1'         => $address1,
                       'address2'         => $address2,
                       'city'             => $city,
                       'state'            => $state,
                       'zip'              => $zip,
                       'country'          => $country,
                       'daytime'          => $daytime,
                       'night'            => $night,
                       'fax'              => $fax,
                       'payby'            => $payby,
                       'payinfo'          => $payinfo,
                       'paycvv'           => $paycvv,
                       'paystart_month'   => $paystart_month
                       'paystart_year'    => $paystart_year,
                       'payissue'         => $payissue,
                       'payip'            => $payip
                       'paydate'          => $paydate,
                       'payname'          => $payname,
                       'invoicing_list'   => $invoicing_list,
                       'referral_custnum' => $referral_custnum,
                       'pkgpart'          => $pkgpart,
                       'username'         => $username,
                       '_password'        => $password,
                       'popnum'           => $popnum,
                       'agentnum'         => $agentnum,
                     }
                   );
 
 my $error = $rv->{'error'};
 if ( $error eq '_decline' ) {
   print_decline();
 } elsif ( $error ) {
   reprint_signup();
 } else {
   print_success();
 }

DESCRIPTION

Use this API to implement your own client "self-service" module.

If you just want to customize the look of the existing "self-service" module, see XXXX instead.

PASSWORD, GECOS, SHELL CHANGING FUNCTIONS

passwd; chfn; chsh

"MY ACCOUNT" FUNCTIONS

login HASHREF

Creates a user session. Takes a hash reference as parameter with the following keys:

username: Username
domain: Domain
password: Password

Returns a hash reference with the following keys:

error: Empty on success, or an error message on errors.
session_id: Session identifier for successful logins

customer_info HASHREF: Returns general customer information.

Takes a hash reference as parameter with a single key: session_id

Returns a hash reference with the following keys:

name: Customer name
balance: Balance owed
open: Array reference of hash references of open inoices. Each hash reference has the following keys: invnum, date, owed
small_custview: An HTML fragment containing shipping and billing addresses.
The following fields are also returned: first last company address1 address2 city county state zip country daytime night fax ship_first ship_last ship_company ship_address1 ship_address2 ship_city ship_state ship_zip ship_country ship_daytime ship_night ship_fax payby payinfo payname month year invoicing_list postal_invoicing

edit_info HASHREF: Takes a hash reference as parameter with any of the following keys:

first last company address1 address2 city county state zip country daytime night fax ship_first ship_last ship_company ship_address1 ship_address2 ship_city ship_state ship_zip ship_country ship_daytime ship_night ship_fax payby payinfo paycvv payname month year invoicing_list postal_invoicing

If a field exists, the customer record is updated with the new value of that field. If a field does not exist, that field is not changed on the customer record.

Returns a hash reference with a single key, error, empty on success, or an error message on errors
invoice HASHREF: Returns an invoice. Takes a hash reference as parameter with two keys: session_id and invnum

Returns a hash reference with the following keys:

error: Empty on success, or an error message on errors
invnum: Invoice number
invoice_text: Invoice text

list_invoices HASHREF: Returns a list of all customer invoices. Takes a hash references with a single key, session_id.

Returns a hash reference with the following keys:

error

Empty on success, or an error message on errors

invoices

Reference to array of hash references with the following keys:

invnum: Invoice ID
_date: Invoice date, in UNIX epoch time

cancel HASHREF: Cancels this customer.

Takes a hash reference as parameter with a single key: session_id

Returns a hash reference with a single key, error, which is empty on success or an error message on errors.
payment_info HASHREF: Returns information that may be useful in displaying a payment page.

Takes a hash reference as parameter with a single key: session_id.

Returns a hash reference with the following keys:

error: Empty on success, or an error message on errors
balance: Balance owed
payname: Exact name on credit card (CARD/DCRD)
address1: Address line one
address2: Address line two
city: City
state: State
zip: Zip or postal code
payby: Customer's current default payment type.
card_type: For CARD/DCRD payment types, the card type (Visa card, MasterCard, Discover card, American Express card, etc.)
payinfo: For CARD/DCRD payment types, the card number
month: For CARD/DCRD payment types, expiration month
year: For CARD/DCRD payment types, expiration year
cust_main_county: County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see FS::cust_main_county). Note these are not FS::cust_main_county objects, but hash references of columns and values.
states: Array reference of all states in the current default country.
card_types: Hash reference of card types; keys are card types, values are the exact strings passed to the process_payment function

process_payment HASHREF

Processes a payment and possible change of address or payment type. Takes a hash reference as parameter with the following keys:

session_id: Session identifier
amount: Amount
save: If true, address and card information entered will be saved for subsequent transactions.
auto: If true, future credit card payments will be done automatically (sets payby to CARD). If false, future credit card payments will be done on-demand (sets payby to DCRD). This option only has meaning if save is set true.
payname: Name on card
address1: Address line one
address2: Address line two
city: City
state: State
zip: Zip or postal code
payinfo: Card number
month: Card expiration month
year: Card expiration year

Returns a hash reference with a single key, error, empty on success, or an error message on errors.
process_payment_order_pkg: Combines the process_payment and order_pkg functions in one step. If the payment processes sucessfully, the package is ordered. Takes a hash reference as parameter with the keys of both methods.

Returns a hash reference with a single key, error, empty on success, or an error message on errors.
process_payment_change_pkg: Combines the process_payment and change_pkg functions in one step. If the payment processes sucessfully, the package is ordered. Takes a hash reference as parameter with the keys of both methods.

Returns a hash reference with a single key, error, empty on success, or an error message on errors.
process_payment_order_renew: Combines the process_payment and order_renew functions in one step. If the payment processes sucessfully, the renewal is processed. Takes a hash reference as parameter with the keys of both methods.

Returns a hash reference with a single key, error, empty on success, or an error message on errors.
list_pkgs: Returns package information for this customer. For more detail on services, see "list_svcs".

Takes a hash reference as parameter with a single key: session_id

Returns a hash reference containing customer package information. The hash reference contains the following keys:

custnum

Customer number

error

Empty on success, or an error message on errors.

cust_pkg HASHREF

Array reference of hash references, each of which has the fields of a cust_pkg record (see FS::cust_pkg) as well as the fields below. Note these are not the internal FS:: objects, but hash references of columns and values.

part_pkg fields

All fields of part_pkg for this specific cust_pkg (be careful with this information - it may reveal more about your available packages than you would like users to know in aggregate)

part_svc

An array of hash references indicating information on unprovisioned services available for provisioning for this specific cust_pkg. Each has the following keys:

part_svc fields: All fields of part_svc (be careful with this information - it may reveal more about your available packages than you would like users to know in aggregate)

cust_svc

An array of hash references indicating information on the customer services already provisioned for this specific cust_pkg. Each has the following keys:

label: Array reference with three elements: The first element is the name of this service. The second element is a meaningful user-specific identifier for the service (i.e. username, domain or mail alias). The last element is the table name of this service.

svcnum: Primary key for this service
svcpart: Service definition (see FS::part_svc)
pkgnum: Customer package (see FS::cust_pkg)
overlimit: Blank if the service is not over limit, or the date the service exceeded its usage limit (as a UNIX timestamp).

list_svcs: Returns service information for this customer.

Takes a hash reference as parameter with a single key: session_id

Returns a hash reference containing customer package information. The hash reference contains the following keys:

custnum

Customer number

svcs

An array of hash references indicating information on all of this customer's services. Each has the following keys:

svcnum: Primary key for this service
label: Name of this service
value: Meaningful user-specific identifier for the service (i.e. username, domain, or mail alias).

Account (svc_acct) services also have the following keys:

username: Username
email: username@domain
seconds: Seconds remaining
upbytes: Upload bytes remaining
downbytes: Download bytes remaining
totalbytes: Total bytes remaining
recharge_amount: Cost of a recharge
recharge_seconds: Number of seconds gained by recharge
recharge_upbytes: Number of upload bytes gained by recharge
recharge_downbytes: Number of download bytes gained by recharge
recharge_totalbytes: Number of total bytes gained by recharge

order_pkg: Orders a package for this customer.