X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=fs_selfservice%2FFS-SelfService%2FSelfService.pm;h=bc54b1ef3660082152f9c2789cf2b92c74f1149c;hp=db9f5fab1a2ca8c5bcff922216d58b2217db06ef;hb=8b4fe72cbd3b29445e336cc3e8cc5dbf5ff02185;hpb=467dfa2d10e8e54bb162554c8f11dca65ec5b565 diff --git a/fs_selfservice/FS-SelfService/SelfService.pm b/fs_selfservice/FS-SelfService/SelfService.pm index db9f5fab1..bc54b1ef3 100644 --- a/fs_selfservice/FS-SelfService/SelfService.pm +++ b/fs_selfservice/FS-SelfService/SelfService.pm @@ -33,6 +33,13 @@ $socket .= '.'.$tag if defined $tag && length($tag); 'switch_cust' => 'MyAccount/switch_cust', 'customer_info' => 'MyAccount/customer_info', 'customer_info_short' => 'MyAccount/customer_info_short', + + 'contact_passwd' => 'MyAccount/contact/contact_passwd', + 'list_contacts' => 'MyAccount/contact/list_contacts', + 'edit_contact' => 'MyAccount/contact/edit_contact', + 'delete_contact' => 'MyAccount/contact/delete_contact', + 'new_contact' => 'MyAccount/contact/new_contact', + 'billing_history' => 'MyAccount/billing_history', 'edit_info' => 'MyAccount/edit_info', #add to ss cgi! 'invoice' => 'MyAccount/invoice', @@ -41,6 +48,9 @@ $socket .= '.'.$tag if defined $tag && length($tag); 'legacy_invoice_pdf' => 'MyAccount/legacy_invoice_pdf', 'invoice_logo' => 'MyAccount/invoice_logo', 'list_invoices' => 'MyAccount/list_invoices', #? + 'list_payby' => 'MyAccount/list_payby', + 'insert_payby' => 'MyAccount/insert_payby', + 'delete_payby' => 'MyAccount/delete_payby', 'cancel' => 'MyAccount/cancel', #add to ss cgi! 'payment_info' => 'MyAccount/payment_info', 'payment_info_renew_info' => 'MyAccount/payment_info_renew_info', @@ -81,12 +91,15 @@ $socket .= '.'.$tag if defined $tag && length($tag); 'part_svc_info' => 'MyAccount/part_svc_info', 'provision_acct' => 'MyAccount/provision_acct', 'provision_phone' => 'MyAccount/provision_phone', + 'provision_pbx' => 'MyAccount/provision_pbx', 'provision_external' => 'MyAccount/provision_external', + 'provision_forward' => 'MyAccount/provision_forward', 'unprovision_svc' => 'MyAccount/unprovision_svc', 'myaccount_passwd' => 'MyAccount/myaccount_passwd', 'reset_passwd' => 'MyAccount/reset_passwd', 'check_reset_passwd' => 'MyAccount/check_reset_passwd', 'process_reset_passwd' => 'MyAccount/process_reset_passwd', + 'validate_passwd' => 'MyAccount/validate_passwd', 'list_tickets' => 'MyAccount/list_tickets', 'create_ticket' => 'MyAccount/create_ticket', 'get_ticket' => 'MyAccount/get_ticket', @@ -99,6 +112,7 @@ $socket .= '.'.$tag if defined $tag && length($tag); 'new_customer' => 'Signup/new_customer', 'new_customer_minimal' => 'Signup/new_customer_minimal', 'capture_payment' => 'Signup/capture_payment', + 'new_prospect' => 'Signup/new_prospect', #N/A 'clear_signup_cache' => 'Signup/clear_cache', 'new_agent' => 'Agent/new_agent', 'agent_login' => 'Agent/agent_login', @@ -115,6 +129,18 @@ $socket .= '.'.$tag if defined $tag && length($tag); 'start_thirdparty' => 'MyAccount/start_thirdparty', 'finish_thirdparty' => 'MyAccount/finish_thirdparty', + + 'list_quotations' => 'MyAccount/quotation/list_quotations', + 'quotation_new' => 'MyAccount/quotation/quotation_new', + 'quotation_delete' => 'MyAccount/quotation/quotation_delete', + 'quotation_info' => 'MyAccount/quotation/quotation_info', + 'quotation_print' => 'MyAccount/quotation/quotation_print', + 'quotation_add_pkg' => 'MyAccount/quotation/quotation_add_pkg', + 'quotation_remove_pkg' => 'MyAccount/quotation/quotation_remove_pkg', + 'quotation_order' => 'MyAccount/quotation/quotation_order', + + 'freesideinc_service' => 'Freeside/freesideinc_service', + ); @EXPORT_OK = ( keys(%autoload), @@ -251,12 +277,60 @@ FS::SelfService - Freeside self-service API #!!! list_pkgs example - #!!! order_pkg example + #ordering a package with an svc_acct service + my $rv = order_pkg( { 'session_id' => $session_id, + 'pkgpart' => $pkgpart, + 'svcpart' => $svcpart, + 'username' => $username, + 'domsvc' => $domsvc, #svcnum of svc_domain + '_password' => $password, + } + ); + + #!!! ordering a package with an svc_domain service example + + #!!! ordering a package with an svc_phone service example + + #!!! ordering a package with an svc_external service example + + #!!! ordering a package with an svc_pbx service + + #ordering a package with no service + my $rv = order_pkg( { 'session_id' => $session_id, + 'pkgpart' => $pkgpart, + 'svcpart' => 'none', + } + ); + + #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 ); + use FS::SelfService qw( signup_info new_customer new_customer_minimal ); my $signup_info = signup_info; @@ -319,6 +393,37 @@ see XXXX instead. =item passwd +Changes the password for an existing user in svc_acct. Takes a hash +reference with the following keys: + +=over 4 + +=item username + +Username of the account (required) + +=item domain + +Domain of the account (required) + +=item old_password + +Old password (required) + +=item new_password + +New password (required) + +=item new_gecos + +New gecos + +=item new_shell + +New Shell + +=back + =item chfn =item chsh @@ -440,7 +545,7 @@ Invoice text =item list_invoices HASHREF -Returns a list of all customer invoices. Takes a hash references with a single +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: @@ -469,6 +574,120 @@ Invoice date, in UNIX epoch time =back +=item list_payby HASHREF + +Returns a list of all stored customer payment information (credit cards and +electronic check accounts). Takes a hash reference with a single key, +session_id. + +Returns a hash reference with the following keys: + +=over 4 + +=item error + +Empty on success, or an error message on errors + +=item payby + +Reference to array of hash references with the following keys: + +=over 4 + +=item custpaybynum + +=item weight + +Numeric weighting. Stored payment information with a lower weight is attempted +first. + +=item payby + +CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD +(on-demand credit card) or DCHK (on-demand electronic check). + +=item paymask + +Masked credit card number (or, masked account and routing numbers) + +=item paydate + +Credit card expiration date + +=item payname + +Exact name on card (or bank name, for electronic checks) + +=item paystate + +For electronic checks, bank state + +=item paytype + +For electronic checks, account type (Personal/Business, Checking/Savings) + +=back + +=back + +=item insert_payby HASHREF + +Adds new stored payment information for this customer. Takes a hash reference +with the following keys: + +=over 4 + +=item session_id + +=item weight + +Numeric weighting. Stored payment information with a lower weight is attempted +first. + +=item payby + +CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD +(on-demand credit card) or DCHK (on-demand electronic check). + +=item payinfo + +Credit card number (or electronic check "account@routing") + +=item paycvv + +CVV2 number / security code + +=item paydate + +Credit card expiration date + +=item payname + +Exact name on card (or bank name, for electronic checks) + +=item paystate + +For electronic checks, bank state + +=item paytype + +For electronic checks, account type (i.e. "Personal Savings", "Personal Checking", "Business Checking")A + +=item payip + +Optional IP address from which payment was submitted + +=back + +If there is an error, returns a hash reference with a single key, B, +otherwise returns a hash reference with a single key, B. + +=item delete_payby HASHREF + +Removes stored payment information. Takes a hash reference with two keys, +B and B. Returns a hash reference with a single key, +B, which is an error message or empty for successful removal. + =item cancel HASHREF Cancels this customer. @@ -853,6 +1072,10 @@ Number of total bytes gained by recharge Orders a package for this customer. +If signup_server-realtime is set, bills the new package, attemps to collect +payment and (for auto-payment customers) cancels the package if the payment is +declined. + Takes a hash reference as parameter with the following keys: =over 4 @@ -869,6 +1092,11 @@ Package to order (see L). Quantity for this package order (default 1). +=item run_bill_events + +If true, runs billing events for the customer after ordering and billing the +package (signup_server-realtime must be set). + =item locationnum Optional locationnum for this package order, for existing locations. @@ -876,13 +1104,22 @@ 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) +(None of this is required at all if you are just ordering a package +at the customer's existing default service location.) + =item address1 -=item address 2 +=item address2 =item city -=item +=item county + +=item state + +=item zip + +=item country =item svcpart @@ -997,6 +1234,10 @@ Existing customer package. New package to order (see L). +=item quantity + +Quantity for this package order (default 1). + =back Returns a hash reference with the following keys: @@ -1038,7 +1279,7 @@ following keys: =item 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 B +Specified as an integer UNIX timestamp. Pass this value to the B function. =item bill_date_pretty @@ -1054,7 +1295,7 @@ Base amount which will be charged if renewed early as of this 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 B. -Specified as a integer UNIX timestamp. +Specified as an integer UNIX timestamp. =item renew_date_pretty @@ -1115,113 +1356,689 @@ Session identifier pkgpart of package to cancel +=item date + +Optional date, for future cancellation (expiration) instead of immediate +cancellation. Specified as an integer UNIX timestamp ("epoch time"). + =back Returns a hash reference with a single key, B, empty on success, or an error message on errors. -=back +=item provision_acct -=head1 SIGNUP FUNCTIONS +Provisions an account (svc_acct). + +Takes a hash reference as parameter with the following keys: =over 4 -=item signup_info HASHREF +=item session_id + +Session identifier + +=item pkgnum + +pkgnum of package into which this service is provisioned + +=item svcpart + +svcpart or service definition to provision + +=item username + +=item domsvc + +=item _password + +=back + +=item provision_phone + +Provisions a phone number (svc_phone). Takes a hash reference as parameter with the following keys: =over 4 -=item session_id - Optional agent/reseller interface session +=item session_id + +Session identifier + +=item pkgnum + +pkgnum of package into which this service is provisioned + +=item svcpart + +svcpart or service definition to provision + +=item countrycode + +=item phonenum + +=item address1 + +=item address2 + +=item city + +=item county + +=item state + +=item zip + +=item country + +E911 Address (optional) =back -Returns a hash reference containing information that may be useful in -displaying a signup page. The hash reference contains the following keys: +=item provision_pbx + +Provisions a customer PBX (svc_pbx). + +Takes a hash reference as parameter with the following keys: =over 4 -=item cust_main_county +=item session_id -County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see L). Note these are not FS::cust_main_county objects, but hash references of columns and values. +Session identifier -=item part_pkg +=item pkgnum -Available packages - array reference of hash references, each of which has the fields of a part_pkg record (see L). Each hash reference also has an additional 'payby' field containing an array reference of acceptable payment types specific to this package (see below and L). 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. +pkgnum of package into which this service is provisioned -=item agent +=item svcpart -Array reference of hash references, each of which has the fields of an agent record (see L). Note these are not FS::agent objects, but hash references of columns and values. +svcpart or service definition to provision -=item agentnum2part_pkg +=item id -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. +=item title -=item svc_acct_pop +=item max_extensions -Access numbers - array reference of hash references, each of which has the fields of an svc_acct_pop record (see L). Note these are not FS::svc_acct_pop objects, but hash references of columns and values. +=item max_simultaneous -=item security_phrase +=item ip_addr -True if the "security_phrase" feature is enabled +=back -=item payby +=item provision_external -Array reference of acceptable payment types for signup +Provisions an external service (svc_external). + +Takes a hash reference as parameter with the following keys: =over 4 -=item CARD +=item session_id -credit card - automatic +Session identifier -=item DCRD +=item pkgnum -credit card - on-demand - version 1.5+ only +pkgnum of package into which this service is provisioned -=item CHEK +=item svcpart -electronic check - automatic +svcpart or service definition to provision -=item DCHK +=item id -electronic check - on-demand - version 1.5+ only +=item title -=item LECB +=back -Phone bill billing +=back -=item BILL +=head2 "MY ACCOUNT" CONTACT FUNCTIONS -billing, not recommended for signups +=over 4 -=item COMP +=item contact_passwd -free, definitely not recommended for signups +Changes the password for the currently-logged in contact. -=item PREPAY +Takes a hash reference as parameter with the following keys: -special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL +=over 4 + +=item session_id + +=item new_password =back -=item cvv_enabled +Returns a hash reference with a single parameter, B, which contains an +error message, or empty on success. -True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch) +=item list_contacts -=item msgcat +Takes a hash reference as parameter with a single key, B. -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". +Returns a hash reference with two parameters: B, which contains an error +message, or empty on success, and B, a list of contacts. -=item statedefault +B is an array reference of hash references (i.e. an array of structs, + in XML-RPC). Each hash reference (struct) has the following keys: -Default state +=over 4 -=item countrydefault +=item contactnum -Default country +=item class + +Contact class name (contact type). + +=item first + +First name + +=item last + +Last name + +=item title + +Position ("Director of Silly Walks"), NOT honorific ("Mr." or "Mrs.") + +=item emailaddress + +Comma-separated list of email addresses + +=item comment + +=item selfservice_access + +Y when enabled + +=back + +=item 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: + +=over 4 + +=item session_id + +=item contactnum + +If already logged in as a contact, this is optional. + +=item first + +=item last + +=item emailaddress + +=back + +Returns a hash reference with a single parameter, B, which contains an +error message, or empty on success. + +=item new_contact + +Creates a new contact. + +Takes a hash reference as parameter with the following keys: + +=over 4 + +=item session_id + +=item first + +=item last + +=item emailaddress + +=item classnum + +Optional contact classnum (TODO: or name) + +=item comment + +=item selfservice_access + +Y to enable self-service access + +=item _password + +=back + +Returns a hash reference with a single parameter, B, which contains an +error message, or empty on success. + +=item 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: + +=over 4 + +=item session_id + +=item contactnum + +=back + +Returns a hash reference with a single parameter, B, which contains an +error message, or empty on success. + +=back + +=head2 "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.` + +=over 4 + +=item list_quotations HASHREF + +Returns a hashref listing this customer's active self-service quotations. +Contents are: + +=over 4 + +=item quotations + +an arrayref containing an element for each quotation. + +=item quotationnum + +the primary key + +=item _date + +the date it was started + +=item num_pkgs + +the number of packages + +=item total_setup + +the sum of setup fees + +=item total_recur + +the sum of recurring charges + +=back + +=item quotation_new HASHREF + +Creates an empty quotation and returns a hashref containing 'quotationnum', +the primary key of the new quotation. + +=item quotation_delete HASHREF + +Disables (does not really delete) a quotation. Takes the following arguments: + +=over 4 + +=item session_id + +=item quotationnum - the quotation to delete + +=back + +Returns 'error' => a string, which will be empty on success. + +=item quotation_info HASHREF + +Returns total and detailed pricing information on a quotation. + +Takes the following arguments: + +=over 4 + +=item session_id + +=item quotationnum - the quotation to return + +=back + +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 + + +=item quotation_print HASHREF + +Renders the quotation as HTML or PDF. Takes the following arguments: + +=over 4 + +=item session_id + +=item quotationnum - the quotation to return + +=item format - 'html' or 'pdf' + +=back + +Returns a hashref containing 'document', the contents of the file. + +=item quotation_add_pkg HASHREF + +Adds a package to a quotation. Takes the following arguments: + +=over 4 + +=item session_id + +=item pkgpart - the package to add + +=item quotationnum - the quotation to add it to + +=item quantity - the package quantity (defaults to 1) + +=item address1, address2, city, state, zip, country - address fields to set +the service location + +=back + +Returns 'error' => a string, which will be empty on success. + +=item quotation_remove_pkg HASHREF + +Removes a package from a quotation. Takes the following arguments: + +=over 4 + +=item session_id + +=item pkgnum - the primary key (quotationpkgnum) of the package to remove + +=item quotationnum - the quotation to remove it from + +=back + +Returns 'error' => a string, which will be empty on success. + +=item quotation_order HASHREF + +Converts the packages in a quotation into real packages. Takes the following +arguments: + +Takes the following arguments: + +=over 4 + +=item session_id + +=item quotationnum - the quotation to order + +=back + +=back + +=head1 SIGNUP FUNCTIONS + +=over 4 + +=item signup_info HASHREF + +Takes a hash reference as parameter with the following keys: + +=over 4 + +=item session_id - Optional agent/reseller interface session + +=back + +Returns a hash reference containing information that may be useful in +displaying a signup page. The hash reference contains the following keys: + +=over 4 + +=item 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 L). Note these are not FS::cust_main_county objects, but hash references of columns and values. + +=item part_pkg + +Available packages - array reference of hash references, each of which has the fields of a part_pkg record (see L). Each hash reference also has an additional 'payby' field containing an array reference of acceptable payment types specific to this package (see below and L). 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. + +=item agent + +Array reference of hash references, each of which has the fields of an agent record (see L). Note these are not FS::agent objects, but hash references of columns and values. + +=item 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. + +=item svc_acct_pop + +Access numbers - array reference of hash references, each of which has the fields of an svc_acct_pop record (see L). Note these are not FS::svc_acct_pop objects, but hash references of columns and values. + +=item security_phrase + +True if the "security_phrase" feature is enabled + +=item payby + +Array reference of acceptable payment types for signup + +=over 4 + +=item CARD + +credit card - automatic + +=item DCRD + +credit card - on-demand - version 1.5+ only + +=item CHEK + +electronic check - automatic + +=item DCHK + +electronic check - on-demand - version 1.5+ only + +=item LECB + +Phone bill billing + +=item BILL + +billing, not recommended for signups + +=item COMP + +free, definitely not recommended for signups + +=item PREPAY + +special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL + +=back + +=item cvv_enabled + +True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch) + +=item 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". + +=item statedefault + +Default state + +=item countrydefault + +Default country + +=back + +=item 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: + +=over 4 + +=item first + +first name (required) + +=item last + +last name (required) + +=item ss + +(not typically collected; mostly used for ACH transactions) + +=item company + +Company name + +=item address1 + +Address line one + +=item address2 + +Address line two + +=item city + +City + +=item county + +County + +=item state + +State + +=item zip + +Zip or postal code + +=item daytime + +Daytime phone number + +=item night + +Evening phone number + +=item fax + +Fax number + +=item payby + +CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L (required) + +=item payinfo + +Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL + +=item paycvv + +Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch) + +=item paydate + +Expiration date for CARD/DCRD + +=item payname + +Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK + +=item 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), + +=item referral_custnum + +referring customer number + +=item agentnum + +Agent number + +=item pkgpart + +pkgpart of initial package + +=item username + +Username + +=item _password + +Password + +=item sec_phrase + +Security phrase + +=item popnum + +Access number (index, not the literal number) + +=item countrycode + +Country code (to be provisioned as a service) + +=item phonenum + +Phone number (to be provisioned as a service) + +=item pin + +Voicemail PIN + +=back + +Returns a hash reference with the following keys: + +=over 4 + +=item 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) =back