htdocs/docs/man/cust_main.txt

   1 NAME
   2     FS::cust_main - Object methods for cust_main records
   3
   4 SYNOPSIS
   5       use FS::cust_main;
   6
   7       $record = new FS::cust_main \%hash;
   8       $record = new FS::cust_main { 'column' => 'value' };
   9
  10       $error = $record->insert;
  11
  12       $error = $new_record->replace($old_record);
  13
  14       $error = $record->delete;
  15
  16       $error = $record->check;
  17
  18       @cust_pkg = $record->all_pkgs;
  19
  20       @cust_pkg = $record->ncancelled_pkgs;
  21
  22       $error = $record->bill;
  23       $error = $record->bill %options;
  24       $error = $record->bill 'time' => $time;
  25
  26       $error = $record->collect;
  27       $error = $record->collect %options;
  28       $error = $record->collect 'invoice_time'   => $time,
  29                                 'batch_card'     => 'yes',
  30                                 'report_badcard' => 'yes',
  31                               ;
  32
  33 DESCRIPTION
  34     An FS::cust_main object represents a customer. FS::cust_main
  35     inherits from FS::Record. The following fields are currently
  36     supported:
  37
  38     custnum - primary key (assigned automatically for new customers)
  39     agentnum - agent (see the FS::agent manpage)
  40     refnum - referral (see the FS::part_referral manpage)
  41     first - name
  42     last - name
  43     ss - social security number (optional)
  44     company - (optional)
  45     address1
  46     address2 - (optional)
  47     city
  48     county - (optional, see the FS::cust_main_county manpage)
  49     state - (see the FS::cust_main_county manpage)
  50     zip
  51     country - (see the FS::cust_main_county manpage)
  52     daytime - phone (optional)
  53     night - phone (optional)
  54     payby - `CARD' (credit cards), `BILL' (billing), or `COMP' (free)
  55     payinfo - card number, P.O.#, or comp issuer (4-8 lowercase alphanumerics; think username)
  56     paydate - expiration date, mm/yyyy, m/yyyy, mm/yy or m/yy
  57     payname - name on card or billing name
  58     tax - tax exempt, empty or `Y'
  59     otaker - order taker (assigned automatically, see the FS::UID manpage)
  60 METHODS
  61     new HASHREF
  62         Creates a new customer. To add the customer to the database,
  63         see the section on "insert".
  64
  65         Note that this stores the hash reference, not a distinct
  66         copy of the hash it points to. You can ask the object for a
  67         copy with the *hash* method.
  68
  69     insert
  70         Adds this customer to the database. If there is an error,
  71         returns the error, otherwise returns false.
  72
  73     delete
  74         Currently unimplemented. Maybe cancel all of this customer's
  75         packages (cust_pkg)?
  76
  77         I don't remove the customer record in the database because
  78         there would then be no record the customer ever existed
  79         (which is bad, no?)
  80
  81     replace OLD_RECORD
  82         Replaces the OLD_RECORD with this one in the database. If
  83         there is an error, returns the error, otherwise returns
  84         false.
  85
  86     check
  87         Checks all fields to make sure this is a valid customer
  88         record. If there is an error, returns the error, otherwise
  89         returns false. Called by the insert and repalce methods.
  90
  91     all_pkgs
  92         Returns all packages (see the FS::cust_pkg manpage) for this
  93         customer.
  94
  95     ncancelled_pkgs
  96         Returns all non-cancelled packages (see the FS::cust_pkg
  97         manpage) for this customer.
  98
  99     bill OPTIONS
 100         Generates invoices (see the FS::cust_bill manpage) for this
 101         customer. Usually used in conjunction with the collect
 102         method.
 103
 104         The only currently available option is `time', which bills
 105         the customer as if it were that time. It is specified as a
 106         UNIX timestamp; see the section on "time" in the perlfunc
 107         manpage). Also see the Time::Local manpage and the
 108         Date::Parse manpage for conversion functions.
 109
 110         If there is an error, returns the error, otherwise returns
 111         false.
 112
 113     collect OPTIONS
 114         (Attempt to) collect money for this customer's outstanding
 115         invoices (see the FS::cust_bill manpage). Usually used after
 116         the bill method.
 117
 118         Depending on the value of `payby', this may print an invoice
 119         (`BILL'), charge a credit card (`CARD'), or just add any
 120         necessary (pseudo-)payment (`COMP').
 121
 122         If there is an error, returns the error, otherwise returns
 123         false.
 124
 125         Currently available options are:
 126
 127         invoice_time - Use this time when deciding when to print
 128         invoices and late notices on those invoices. The default is
 129         now. It is specified as a UNIX timestamp; see the section on
 130         "time" in the perlfunc manpage). Also see the Time::Local
 131         manpage and the Date::Parse manpage for conversion
 132         functions.
 133
 134         batch_card - Set this true to batch cards (see the
 135         cust_pay_batch manpage). By default, cards are processed
 136         immediately, which will generate an error if CyberCash is
 137         not installed.
 138
 139         report_badcard - Set this true if you want bad card
 140         transactions to return an error. By default, they don't.
 141
 142     total_owed
 143         Returns the total owed for this customer on all invoices
 144         (see the FS::cust_bill manpage).
 145
 146     total_credited
 147         Returns the total credits (see the FS::cust_credit manpage)
 148         for this customer.
 149
 150     balance
 151         Returns the balance for this customer (total owed minus
 152         total credited).
 153
 154     invoicing_list [ ARRAYREF ]
 155         If an arguement is given, sets these email addresses as
 156         invoice recipients (see the FS::cust_main_invoice manpage).
 157         Errors are not fatal and are not reported (except as
 158         warnings), so use check_invoicing_list first.
 159
 160         Returns a list of email addresses (with svcnum entries
 161         expanded).
 162
 163         Note: You can clear the invoicing list by passing an empty
 164         ARRAYREF. You can check it without disturbing anything by
 165         passing nothing.
 166
 167         This interface may change in the future.
 168
 169     check_invoicing_list ARRAYREF
 170         Checks these arguements as valid input for the
 171         invoicing_list method. If there is an error, returns the
 172         error, otherwise returns false.
 173
 174 VERSION
 175     $Id: cust_main.txt,v 1.3 1999-02-09 09:37:58 ivan Exp $
 176
 177 BUGS
 178     The delete method.
 179
 180     Bill and collect options should probably be passed as references
 181     instead of a list.
 182
 183     CyberCash v2 forces us to define some variables in package main.
 184
 185     There should probably be a configuration file with a list of
 186     allowed credit card types.
 187
 188     CyberCash is the only processor.
 189
 190     No multiple currency support (probably a larger project than
 191     just this module).
 192
 193 SEE ALSO
 194     the FS::Record manpage, the FS::cust_pkg manpage, the
 195     FS::cust_bill manpage, the FS::cust_credit manpage the
 196     FS::cust_pay_batch manpage, the FS::agent manpage, the
 197     FS::part_referral manpage, the FS::cust_main_county manpage, the
 198     FS::cust_main_invoice manpage, the FS::UID manpage, schema.html
 199     from the base documentation.
 200
 201 HISTORY
 202     ivan@voicenet.com 97-jul-28
 203
 204     Changed to standard Business::CreditCard no more TableUtil
 205     EXPORT_OK FS::Record's hfields removed unique calls and locking
 206     (not needed here now) wrapped the (now) optional fields in if
 207     statements in sub check (notyetdone!) ivan@sisd.com 97-nov-12
 208
 209     updated paydate with SQL-type date info ivan@sisd.com 98-mar-5
 210
 211     Added export of datasrc from UID.pm for Pg6.3 changed 'day' to
 212     'daytime' because Pg6.3 reserves the day word
 213     bmccane@maxbaud.net 98-apr-3
 214
 215     in ->create, s/svc_acct/cust_main/, now it should actually
 216     eliminate the warnings it was meant to ivan@sisd.com 98-jul-16
 217
 218     don't require a phone number and allow '/' in company names
 219     ivan@sisd.com 98-jul-18
 220
 221     use ut_ and rewrite &check, &*_pkgs ivan@sisd.com 98-sep-5
 222
 223     pod, merge with FS::Bill (about time!), total_owed,
 224     total_credited and balance methods, cleaned collect method,
 225     source modifications no longer necessary to enable cybercash,
 226     cybercash v3 support, don't need to import
 227     FS::UID::{datasrc,checkruid} ivan@sisd.com 98-sep-19-21
 228
 229     $Log: cust_main.txt,v $
 230     Revision 1.3  1999-02-09 09:37:58  ivan
 231     regenerated perl api docs from embedded pod
 232  Revision 1.10 1999/01/25 12:26:09 ivan
 233     yet more mod_perl stuff
 234
 235     Revision 1.9 1999/01/18 09:22:41 ivan changes to track email
 236     addresses for email invoicing
 237
 238     Revision 1.8 1998/12/29 11:59:39 ivan mostly properly OO, some
 239     work still to be done with svc_ stuff
 240
 241     Revision 1.7 1998/12/16 09:58:52 ivan library support for
 242     editing email invoice destinations (not in sub collect yet)
 243
 244     Revision 1.6 1998/11/18 09:01:42 ivan i18n! i18n!
 245
 246     Revision 1.5 1998/11/15 11:23:14 ivan use FS::table_name for all
 247     searches to eliminate warnings, emit state/county when they
 248     don't match
 249
 250     Revision 1.4 1998/11/15 05:30:48 ivan bugfix for new config
 251     layout
 252
 253     Revision 1.3 1998/11/13 09:56:54 ivan change configuration file
 254     layout to support multiple distinct databases (with own set of
 255     config files, export, etc.)
 256
 257     Revision 1.2 1998/11/07 10:24:25 ivan don't use depriciated
 258     FS::Bill and FS::Invoice, other miscellania
 259