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

From Freeside
Jump to: navigation, search
m (Edit via perl MediaWiki framework (1.13))
m (Edit via perl MediaWiki framework (1.13))
 
(One intermediate revision by the same user not shown)
Line 211: Line 211:
 
::Invoice text
 
::Invoice text
 
; list_invoices HASHREF
 
; list_invoices HASHREF
:Returns a list of all customer invoices. Takes a hash references with a single key, session_id.
+
:Returns a list of all customer invoices. Takes a hash reference with a single key, session_id.
  
 
:Returns a hash reference with the following keys:
 
:Returns a hash reference with the following keys:
Line 499: Line 499:
 
:Provisions an account (svc_acct).
 
:Provisions an account (svc_acct).
  
:Takes a hash references as parameter with the following keys:
+
:Takes a hash reference as parameter with the following keys:
 
:; session_id
 
:; session_id
 
::Session identifier
 
::Session identifier
Line 509: Line 509:
 
:Provisions a phone number (svc_phone).
 
:Provisions a phone number (svc_phone).
  
:Takes a hash references as parameter with the following keys:
+
:Takes a hash reference as parameter with the following keys:
 
:; session_id
 
:; session_id
 
::Session identifier
 
::Session identifier
Line 521: Line 521:
 
:Provisions a customer PBX (svc_pbx).
 
:Provisions a customer PBX (svc_pbx).
  
:Takes a hash references as parameter with the following keys:
+
:Takes a hash reference as parameter with the following keys:
 
:; session_id
 
:; session_id
 
::Session identifier
 
::Session identifier
Line 531: Line 531:
 
:Provisions an external service (svc_external).
 
:Provisions an external service (svc_external).
  
:Takes a hash references as parameter with the following keys:
+
:Takes a hash reference as parameter with the following keys:
 
:; session_id
 
:; session_id
 
::Session identifier
 
::Session identifier
Line 539: Line 539:
 
::svcpart or service definition to provision
 
::svcpart or service definition to provision
 
:; id:; title
 
:; id:; title
 +
==="MY ACCOUNT" CONTACT FUNCTIONS===
 +
; contact_passwd
 +
:Changes the password for the currently-logged in contact.
 +
 +
:Takes a hash reference as parameter with the following keys:
 +
:; session_id:; new_password
 +
:Returns a hash reference with a single parameter, '''error''', which contains an error message, or empty on success.
 +
; list_contacts
 +
:Takes a hash reference as parameter with a single key, '''session_id'''.
 +
 +
:Returns a hash reference with two parameters: '''error''', which contains an error message, or empty on success, and '''contacts''', a list of contacts.
 +
 +
:'''contacts''' is an array reference of hash references (i.e. an array of structs, in XML-RPC). Each hash reference (struct) has the following keys:
 +
; contactnum; class
 +
:Contact class name (contact type).
 +
; first
 +
:First name
 +
; last
 +
:Last name
 +
; title
 +
:Position ("Director of Silly Walks"), NOT honorific ("Mr." or "Mrs.")
 +
; emailaddress
 +
:Comma-separated list of email addresses
 +
; comment; selfservice_access
 +
:Y when enabled
 +
 +
; edit_contact
 +
:Updates information for the currently-logged in contact, or (optionally) the specified contact.
 +
 +
:Takes a hash reference as parameter with the following keys:
 +
:; session_id:; contactnum
 +
::If already logged in as a contact, this is optional.
 +
:; first:; last:; emailaddress
 +
:Returns a hash reference with a single parameter, '''error''', which contains an error message, or empty on success.
 +
; new_contact
 +
:Creates a new contact.
 +
 +
:Takes a hash reference as parameter with the following keys:
 +
:; session_id:; first:; last:; emailaddress:; classnum
 +
::Optional contact classnum (TODO: or name)
 +
:; comment:; selfservice_access
 +
::Y to enable self-service access
 +
:; _password
 +
:Returns a hash reference with a single parameter, '''error''', which contains an error message, or empty on success.
 +
; delete_contact
 +
:Deletes a contact. (Note: Cannot at this time delete the currently-logged in contact.)
 +
 +
:Takes a hash reference as parameter with the following keys:
 +
:; session_id:; contactnum
 +
:Returns a hash reference with a single parameter, '''error''', which contains an error message, or empty on success.
 +
 
==="MY ACCOUNT" QUOTATION FUNCTIONS===
 
==="MY ACCOUNT" QUOTATION FUNCTIONS===
 
All of these functions require the user to be logged in, and the 'session_id' key to be included in the argument hashref.`
 
All of these functions require the user to be logged in, and the 'session_id' key to be included in the argument hashref.`
Line 544: Line 595:
 
; list_quotations HASHREF
 
; list_quotations HASHREF
 
:Returns a hashref listing this customer's active self-service quotations. Contents are:
 
:Returns a hashref listing this customer's active self-service quotations. Contents are:
 
+
:; quotations
:- 'quotations', an arrayref containing an element for each quotation. - quotationnum, the primary key - _date, the date it was started - num_pkgs, the number of packages - total_setup, the sum of setup fees - total_recur, the sum of recurring charges
+
::an arrayref containing an element for each quotation.
 +
:; quotationnum
 +
::the primary key
 +
:; _date
 +
::the date it was started
 +
:; num_pkgs
 +
::the number of packages
 +
:; total_setup
 +
::the sum of setup fees
 +
:; total_recur
 +
::the sum of recurring charges
 
; quotation_new HASHREF
 
; quotation_new HASHREF
 
:Creates an empty quotation and returns a hashref containing 'quotationnum', the primary key of the new quotation.
 
:Creates an empty quotation and returns a hashref containing 'quotationnum', the primary key of the new quotation.
Line 831: Line 892:
 
Hey! '''The above document had some coding errors, which are explained below:'''
 
Hey! '''The above document had some coding errors, which are explained below:'''
  
; Around line 1447:
+
; Around line 1362:
 +
:Unknown directive: =over4
 +
; Around line 1394:
 +
:'=item' outside of any '=over'
 +
; Around line 1471:
 +
:You forgot a '=back' before '=head2'
 +
; Around line 1616:
 
:'=item' outside of any '=over'
 
:'=item' outside of any '=over'

Latest revision as of 07:39, 28 September 2015

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

 #new-style login with an email address and password
 # can also be used for svc_acct login, set $emailaddress to username@domain
 my $rv = login ( { 'email'    => $emailaddress,
                    'password' => $password,
                  },
                );
 if ( $rv->{'error'} ) {
   #handle login error...
 } else {
   #successful login
   $session_id = $rv->{'session_id'};
 }

 #classic svc_acct-based login with separate username and password
 my $rv = login( { 'username' => $username,
                   'domain'   => $domain,
                   'password' => $password,
                 }
               );
 if ( $rv->{'error'} ) {
   #handle login error...
 } else {
   #successful login
   $session_id = $rv->{'session_id'};
 }

 #svc_phone login with phone number and PIN
 my $rv = login( { 'username' => $phone_number,
                   'domain'   => 'svc_phone',
                   'password' => $pin,
                 }
               );
 if ( $rv->{'error'} ) {
   #handle login error...
 } else {
   #successful login
   $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

 #quoting a package, then ordering after confirmation

 my $rv = quotation_new({ 'session_id' => $session_id });
 my $qnum = $rv->{quotationnum};
 #  add packages to the quotation
 $rv = quotation_add_pkg({ 'session_id'   => $session_id,
                           'quotationnum' => $qnum,
                           'pkgpart'      => $pkgpart,
                           'quantity'     => $quantity, # defaults to 1
                         });
 #  repeat until all packages are added
 #  view the pricing information
 $rv = quotation_info({ 'session_id'   => $session_id,
                        'quotationnum' => $qnum,
                     });
 print "Total setup charges: ".$rv->{total_setup}."\n".
       "Total recurring charges: ".$rv->{total_recur}."\n";
 #  quotation_info also provides a detailed breakdown of charges, in
 #  $rv->{sections}.

 #  ask customer for confirmation, then:
 $rv = quotation_order({ 'session_id'   => $session_id,
                         'quotationnum' => $qnum,
                       });

 #!!! cancel_pkg example

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

 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,
                       'agentnum'         => $agentnum,
                       'pkgpart'          => $pkgpart,

                       'username'         => $username,
                       '_password'        => $password,
                       'popnum'           => $popnum,
                       #OR
                       'countrycode'      => 1,
                       'phonenum'         => $phonenum,
                       'pin'              => $pin,
                     }
                   );
 
 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
Changes the password for an existing user in svc_acct. Takes a hash reference with the following keys:
username
Username of the account (required)
domain
Domain of the account (required)
old_password
Old password (required)
new_password
New password (required)
new_gecos
New gecos
new_shell
New Shell
chfn; chsh

"MY ACCOUNT" FUNCTIONS

login HASHREF
Creates a user session. Takes a hash reference as parameter with the following keys:
email
Email address (username@domain), instead of username and domain. Required for contact-based self-service login, can also be used for svc_acct-based login.
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 reference 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
country
Two-letter country 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.
Takes a hash reference as parameter with the following keys:
session_id
Session identifier
pkgpart
Package to order (see FS::part_pkg).
quantity
Quantity for this package order (default 1).
locationnum
Optional locationnum for this package order, for existing locations.
Or, for new locations, pass the following fields: address1*, address2, city*, county, state*, zip*, country. (* = required in this case)
address1
; address 2:; city:; :; svcpart
Service to order (see FS::part_svc).
Normally optional; required only to provision a non-svc_acct service, or if the package definition does not contain one svc_acct service definition with quantity 1 (it may contain others with quantity >1). A svcpart of "none" can also be specified to indicate that no initial service should be provisioned.
Fields used when provisioning an svc_acct service:
username
Username
_password
Password
sec_phrase
Optional security phrase
popnum
Optional Access number number
Fields used when provisioning an svc_domain service:
domain
Domain
Fields used when provisioning an svc_phone service:
phonenum
Phone number
pin
Voicemail PIN
sip_password
SIP password
Fields used when provisioning an svc_external service:
id
External numeric ID.
title
External text title.
Fields used when provisioning an svc_pbx service:
id
Numeric ID.
name
Text name.
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.
change_pkg
Changes a package for this customer.
Takes a hash reference as parameter with the following keys:
session_id
Session identifier
pkgnum
Existing customer package.
pkgpart
New package to order (see FS::part_pkg).
quantity
Quantity for this package order (default 1).
Returns a hash reference with the following keys:
error
Empty on success, or an error message on errors.
pkgnum
On success, the new pkgnum
renew_info
Provides useful info for early renewals.
Takes a hash reference as parameter with the following keys:
session_id
Session identifier
Returns a hash reference. On errors, it contains a single key, error, with the error message. Otherwise, contains a single key, dates, pointing to an array refernce of hash references. Each hash reference contains the following keys:
bill_date
(Future) Bill date. Indicates a future date for which billing could be run. Specified as a integer UNIX timestamp. Pass this value to the order_renew function.
bill_date_pretty
(Future) Bill date as a human-readable string. (Convenience for display; subject to change, so best not to parse for the date.)
amount
Base amount which will be charged if renewed early as of this date.
renew_date
Renewal date; i.e. even-futher future date at which the customer will be paid through if the early renewal is completed with the given bill-date. Specified as a integer UNIX timestamp.
renew_date_pretty
Renewal date as a human-readable string. (Convenience for display; subject to change, so best not to parse for the date.)
pkgnum
Package that will be renewed.
expire_date
Expiration date of the package that will be renewed.
expire_date_pretty
Expiration date of the package that will be renewed, as a human-readable string. (Convenience for display; subject to change, so best not to parse for the date.)
order_renew
Renews this customer early; i.e. runs billing for this customer in advance.
Takes a hash reference as parameter with the following keys:
session_id
Session identifier
date
Integer date as returned by the renew_info function, indicating the advance date for which to run billing.
Returns a hash reference with a single key, error, empty on success, or an error message on errors.
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.
provision_acct
Provisions an account (svc_acct).
Takes a hash reference as parameter with the following keys:
session_id
Session identifier
pkgnum
pkgnum of package into which this service is provisioned
svcpart
svcpart or service definition to provision
username
; domsvc:; _password; provision_phone
Provisions a phone number (svc_phone).
Takes a hash reference as parameter with the following keys:
session_id
Session identifier
pkgnum
pkgnum of package into which this service is provisioned
svcpart
svcpart or service definition to provision
countrycode
; phonenum:; address1:; address2:; city:; county:; state:; zip:; country
E911 Address (optional)
provision_pbx
Provisions a customer PBX (svc_pbx).
Takes a hash reference as parameter with the following keys:
session_id
Session identifier
pkgnum
pkgnum of package into which this service is provisioned
svcpart
svcpart or service definition to provision
id
; title:; max_extensions:; max_simultaneous:; ip_addr; provision_external
Provisions an external service (svc_external).
Takes a hash reference as parameter with the following keys:
session_id
Session identifier
pkgnum
pkgnum of package into which this service is provisioned
svcpart
svcpart or service definition to provision
id
; title

"MY ACCOUNT" CONTACT FUNCTIONS

contact_passwd
Changes the password for the currently-logged in contact.
Takes a hash reference as parameter with the following keys:
session_id
; new_password
Returns a hash reference with a single parameter, error, which contains an error message, or empty on success.
list_contacts
Takes a hash reference as parameter with a single key, session_id.
Returns a hash reference with two parameters: error, which contains an error message, or empty on success, and contacts, a list of contacts.
contacts is an array reference of hash references (i.e. an array of structs, in XML-RPC). Each hash reference (struct) has the following keys:
contactnum; class
Contact class name (contact type).
first
First name
last
Last name
title
Position ("Director of Silly Walks"), NOT honorific ("Mr." or "Mrs.")
emailaddress
Comma-separated list of email addresses
comment; selfservice_access
Y when enabled
edit_contact
Updates information for the currently-logged in contact, or (optionally) the specified contact.
Takes a hash reference as parameter with the following keys:
session_id
; contactnum
If already logged in as a contact, this is optional.
first
; last:; emailaddress
Returns a hash reference with a single parameter, error, which contains an error message, or empty on success.
new_contact
Creates a new contact.
Takes a hash reference as parameter with the following keys:
session_id
; first:; last:; emailaddress:; classnum
Optional contact classnum (TODO: or name)
comment
; selfservice_access
Y to enable self-service access
_password
Returns a hash reference with a single parameter, error, which contains an error message, or empty on success.
delete_contact
Deletes a contact. (Note: Cannot at this time delete the currently-logged in contact.)
Takes a hash reference as parameter with the following keys:
session_id
; contactnum
Returns a hash reference with a single parameter, error, which contains an error message, or empty on success.

"MY ACCOUNT" QUOTATION FUNCTIONS

All of these functions require the user to be logged in, and the 'session_id' key to be included in the argument hashref.`

list_quotations HASHREF
Returns a hashref listing this customer's active self-service quotations. Contents are:
quotations
an arrayref containing an element for each quotation.
quotationnum
the primary key
_date
the date it was started
num_pkgs
the number of packages
total_setup
the sum of setup fees
total_recur
the sum of recurring charges
quotation_new HASHREF
Creates an empty quotation and returns a hashref containing 'quotationnum', the primary key of the new quotation.
quotation_delete HASHREF
Disables (does not really delete) a quotation. Takes the following arguments:
session_id
; quotationnum - the quotation to delete
Returns 'error' => a string, which will be empty on success.
quotation_info HASHREF
Returns total and detailed pricing information on a quotation.
Takes the following arguments:
session_id
; quotationnum - the quotation to return
Returns a hashref containing:
- total_setup, the total of setup fees (and their taxes) - total_recur, the total of all recurring charges (and their taxes) - sections, an arrayref containing an element for each quotation section. - description, a line of text describing the group of charges - subtotal, the total of charges in this group (if appropriate) - detail_items, an arrayref of line items - pkgnum, the reference number of the package - description, the package name (or tax name) - quantity - amount, the amount charged If the detail item represents a subtotal, it will instead contain: - total_item: description of the subtotal - total_amount: the subtotal amount
quotation_print HASHREF
Renders the quotation as HTML or PDF. Takes the following arguments:
session_id
; quotationnum - the quotation to return:; format - 'html' or 'pdf'
Returns a hashref containing 'document', the contents of the file.
quotation_add_pkg HASHREF
Adds a package to a quotation. Takes the following arguments:
session_id
; pkgpart - the package to add:; quotationnum - the quotation to add it to:; quantity - the package quantity (defaults to 1):; address1, address2, city, state, zip, country - address fields to set the service location
Returns 'error' => a string, which will be empty on success.
quotation_remove_pkg HASHREF
Removes a package from a quotation. Takes the following arguments:
session_id
; pkgnum - the primary key (quotationpkgnum) of the package to remove:; quotationnum - the quotation to remove it from
Returns 'error' => a string, which will be empty on success.
quotation_order HASHREF
Converts the packages in a quotation into real packages. Takes the following arguments:
Takes the following arguments:
session_id
; quotationnum - the quotation to order

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_minimal HASHREF
Creates a new customer.
Current differences from new_customer: An address is not required. promo_code and reg_code are not supported. If invoicing_list and _password is passed, a contact will be created with self-service access (no pkgpart or username is necessary). No initial billing is run (this may change in a future version).
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
Address line one
address2
Address line two
city
City
county
County
state
State
zip
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
agentnum
Agent number
pkgpart
pkgpart of initial package
username
Username
_password
Password
sec_phrase
Security phrase
popnum
Access number (index, not the literal number)
countrycode
Country code (to be provisioned as a service)
phonenum
Phone number (to be provisioned as a service)
pin
Voicemail PIN
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)
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
agentnum
Agent number
pkgpart
pkgpart of initial package
username
Username
_password
Password
sec_phrase
Security phrase
popnum
Access number (index, not the literal number)
countrycode
Country code (to be provisioned as a service)
phonenum
Phone number (to be provisioned as a service)
pin
Voicemail PIN
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.
location_form HASHREF | LIST
Takes as input a hashref or list of key/value pairs with the following keys:
session_id
Current customer session_id
no_asterisks
Omit red asterisks from required fields.
address1_label
Label for first address line.
Returns an HTML fragment for a location form (address, city, state, zip, country)
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.
domainselector HASHREF | LIST
Takes as input a hashref or list of key/value pairs with the following keys:
pkgnum
Package number
domsvc
Service number of the selected item.
Returns an HTML fragment for domain selection.
didselector HASHREF | LIST
Takes as input a hashref or list of key/value pairs with the following keys:
field
Field name for the returned HTML fragment.
svcpart
Service definition (see FS::part_svc)
Returns an HTML fragment for DID 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.

For the most part, development of the reseller web interface has been superceded by agent-virtualized access to the backend.

agent_login
Agent login
agent_info
Agent info
agent_list_customers
List agent's customers.

BUGS

SEE ALSO

freeside-selfservice-clientd, freeside-selfservice-server

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 1362:
Unknown directive: =over4
Around line 1394:
'=item' outside of any '=over'
Around line 1471:
You forgot a '=back' before '=head2'
Around line 1616:
'=item' outside of any '=over'