Difference between revisions of "Freeside:1.7:Documentation:Developer/FS/SelfService"

Revision as of 19:22, 3 October 2007

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

paybatch

Unique transaction identifier (prevents multiple charges), 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

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

paybatch

Unique transaction identifier, returned from the payment_info function. Prevents multiple charges.

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.

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:

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 (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, each of which 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)

error

Empty on success, or an error message on errors.

order_pkg

Orders a package for this customer.

Takes a hash reference as parameter with the following keys:

session_id

Session identifier

pkgpart

pkgpart of package to order

svcpart

optional svcpart, required only if the package definition does not contain one svc_acct service definition with quantity 1 (it may contain others with quantity >1)

username

Username

_password

Password

sec_phrase

Optional security phrase

popnum

Optional Access number number

Returns a hash reference with a single key, error, empty on success, or an error message on errors. The special error '_decline' is returned for declined transactions.

cancel_pkg

Cancels a package for this customer.

Takes a hash reference as parameter with the following keys:

session_id

Session identifier

pkgpart

pkgpart of package to cancel

Returns a hash reference with a single key, error, empty on success, or an error message on errors.

SIGNUP FUNCTIONS

signup_info HASHREF

Takes a hash reference as parameter with the following keys:

session_id - Optional agent/reseller interface session

Returns a hash reference containing information that may be useful in displaying a signup page. The hash reference contains the following keys:

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.

part_pkg

Available packages - array reference of hash references, each of which has the fields of a part_pkg record (see FS::part_pkg). Each hash reference also has an additional 'payby' field containing an array reference of acceptable payment types specific to this package (see below and "payby" in FS/part pkg|FS::part_pkg#payby|"payby" in FS::part_pkg). Note these are not FS::part_pkg objects, but hash references of columns and values. Requires the 'signup_server-default_agentnum' configuration value to be set, or an agentnum specified explicitly via reseller interface session_id in the options.

agent

Array reference of hash references, each of which has the fields of an agent record (see FS::agent). Note these are not FS::agent objects, but hash references of columns and values.

agentnum2part_pkg

Hash reference; keys are agentnums, values are array references of available packages for that agent, in the same format as the part_pkg arrayref above.

svc_acct_pop

Access numbers - array reference of hash references, each of which has the fields of an svc_acct_pop record (see FS::svc_acct_pop). Note these are not FS::svc_acct_pop objects, but hash references of columns and values.

security_phrase

True if the "security_phrase" feature is enabled

payby

Array reference of acceptable payment types for signup

CARD

credit card - automatic

DCRD

credit card - on-demand - version 1.5+ only

CHEK

electronic check - automatic

DCHK

electronic check - on-demand - version 1.5+ only

LECB

Phone bill billing

BILL

billing, not recommended for signups

COMP

free, definitely not recommended for signups

PREPAY

special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL

cvv_enabled

True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)

msgcat

Hash reference of message catalog values, to support error message customization. Currently available keys are: passwords_dont_match, invalid_card, unknown_card_type, and not_a (as in "Not a Discover card"). Values are configured in the web interface under "View/Edit message catalog".

statedefault

Default state

countrydefault

Default country

new_customer HASHREF

Creates a new customer. Takes a hash reference as parameter with the following keys:

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

address2

Address line two

city (required)

City

county

County

state (required)

State

zip (required)

Zip or postal code

daytime

Daytime phone number

night

Evening phone number

fax

Fax number

payby

CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see "signup_info" (required)

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

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

referral_custnum

referring customer number

pkgpart

pkgpart of initial package

username

Username

_password

Password

sec_phrase

Security phrase

popnum

Access number (index, not the literal number)

agentnum

Agent number

Returns a hash reference with the following keys:

error

Empty on success, or an error message on errors. The special error '_decline' is returned for declined transactions; other error messages should be suitable for display to the user (and are customizable in under Configuration | View/Edit message catalog)

regionselector HASHREF | LIST

Takes as input a hashref or list of key/value pairs with the following keys:

selected_county

Currently selected county

selected_state

Currently selected state

selected_country

Currently selected country

prefix

Specify a unique prefix string if you intend to use the HTML output multiple time son one page.

onchange

Specify a javascript subroutine to call on changes

default_state

Default state

default_country

Default country

locales

An arrayref of hash references specifying regions. Normally you can just pass the value of the cust_main_county field returned by signup_info.

Returns a list consisting of three HTML fragments for county selection, state selection and country selection, respectively.

expselect PREFIX [ DATE ]

Takes as input a unique prefix string and the current expiration date, in yyyy-mm-dd or m-d-yyyy format

Returns an HTML fragments for expiration date selection.

popselector HASHREF | LIST

Takes as input a hashref or list of key/value pairs with the following keys:

popnum

Access number number

pops

An arrayref of hash references specifying access numbers. Normally you can just pass the value of the svc_acct_pop field returned by signup_info.

Returns an HTML fragment for access number selection.

RESELLER FUNCTIONS

Note: Resellers can also use the signup_info and new_customer functions with their active session, and the customer_info and order_pkg functions with their active session and an additional custnum parameter.

agent_login; agent_info; agent_list_customers

BUGS

SEE ALSO

freeside-selfservice-clientd, freeside-selfservice-server