.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "LedgerSMB::DBObject::Payment 3pm" .TH LedgerSMB::DBObject::Payment 3pm "2012-03-25" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" LedgerSMB::DBOject::Payment \- Payment Handling Back\-end Routines for LedgerSMB .SH "SYNOPSIS" .IX Header "SYNOPSIS" Provides the functions for generating the data structures payments made in LedgerSMB. This module currently handles only basic payment logic, and does handle overpayment logic, though these features will be moved into this module in the near future. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2007 The LedgerSMB Core Team. Licensed under the \s-1GNU\s0 General Public License version 2 or at your option any later version. Please see the included \s-1COPYRIGHT\s0 and \s-1LICENSE\s0 files for more information. .SH "METHODS" .IX Header "METHODS" .IP "LedgerSMB::DBObject::Payment\->\fInew()\fR" 4 .IX Item "LedgerSMB::DBObject::Payment->new()" Inherited from LedgerSMB::DBObject. Please see that documnetation for details. .ie n .IP "$payment\->\fIget_open_accounts()\fR" 4 .el .IP "\f(CW$payment\fR\->\fIget_open_accounts()\fR" 4 .IX Item "$payment->get_open_accounts()" This function returns a list of open accounts depending on the \&\f(CW$payment\fR\->{account_class} property. If this property is 1, it returns a list of vendor accounts, for 2, a list of customer accounts are returned. .Sp The returned list of hashrefs is stored in the \f(CW$payment\fR\->{accounts} property. Each hashref has the following keys: id (entity id), name, and entity_class. .Sp An account is considered open if there are outstanding, unpaid invoices attached to it. Customer/vendor payment threshold is not considered for this calculation. .IP "text_amount($value)" 4 .IX Item "text_amount($value)" Returns the textual representation, as defined in localization rules, for the numeric value passed. .IP "\fIget_metadata()\fR" 4 .IX Item "get_metadata()" Semi-private method for preparing the object for other tasks, such as displaying payment options. .IP "\fIsearch()\fR" 4 .IX Item "search()" Seturns a series of payments matching the search criteria. .Sp Search results are also stored at \f(CW$payment\fR\->{search_results}. .IP "\fIget_open_accounts()\fR" 4 .IX Item "get_open_accounts()" Returns a list of open accounts for the payment operation. .Sp These are also stored on \f(CW$payment\fR\->{accounts} .ie n .IP "$payment\->\fIget_entity_credit_account()\fR" 4 .el .IP "\f(CW$payment\fR\->\fIget_entity_credit_account()\fR" 4 .IX Item "$payment->get_entity_credit_account()" Returns billing information for the current account, and saves it to an arrayref at \f(CW$payment\fR\->{entity_accounts}/ .ie n .IP "$payment\->\fIget_all_accounts()\fR" 4 .el .IP "\f(CW$payment\fR\->\fIget_all_accounts()\fR" 4 .IX Item "$payment->get_all_accounts()" This function returns a list of open or closed accounts depending on the \&\f(CW$payment\fR\->{account_class} property. If this property is 1, it returns a list of vendor accounts, for 2, a list of customer accounts are returned. .Sp The returned list of hashrefs is stored in the \f(CW$payment\fR\->{accounts} property. Each hashref has the following keys: id (entity id), name, and entity_class. .ie n .IP "$payment\->\fIreverse()\fR" 4 .el .IP "\f(CW$payment\fR\->\fIreverse()\fR" 4 .IX Item "$payment->reverse()" This function reverses a payment. A payment is defined as one source ($payment\->{source}) to one cash account ($payment\->{cash_accno}) to one date ($payment\->{date_paid}) to one vendor/customer ($payment\->{credit_id}, \&\f(CW$payment\fR\->{account_class}). This reverses the entries with that source. .ie n .IP "$payment\->\fIget_open_invoices()\fR" 4 .el .IP "\f(CW$payment\fR\->\fIget_open_invoices()\fR" 4 .IX Item "$payment->get_open_invoices()" This function returns a list of open invoices depending on the \&\f(CW$payment\fR\->{account_class}, \f(CW$payment\fR\->{entity_id}, and \f(CW$payment\fR\->{curr} properties. Account classes follow the conventions above. This list is hence specific to a customer or vendor and currency as well. .Sp The returned list of hashrefs is stored in the \f(CW$payment\fR\->{open_invoices} property. Each hashref has the following keys: id (entity id), name, and entity_class. .ie n .IP "$payment\->\fIget_open_invoice()\fR" 4 .el .IP "\f(CW$payment\fR\->\fIget_open_invoice()\fR" 4 .IX Item "$payment->get_open_invoice()" This function is an especific case of \fIget_open_invoices()\fR, because \fIget_open_invoice()\fR can search for a specific invoice, wich can be searched by the \f(CW$payment\fR\->{invnumber} variable .ie n .IP "$payment\->\fIget_all_contact_invoices()\fR" 4 .el .IP "\f(CW$payment\fR\->\fIget_all_contact_invoices()\fR" 4 .IX Item "$payment->get_all_contact_invoices()" This function returns a list of open accounts depending on the \&\f(CW$payment\fR\->{account_class} property. If this property is 1, it returns a list of vendor accounts, for 2, a list of customer accounts are returned. Attached to each account is a list of open invoices. The data structure is somewhat complex. .Sp Each item in the list has the following keys: contact_id, contact_name, \e account_number, total_due, and invoices. .Sp The invoices entry is a reference to an array of hashrefs. Each of these hashrefs has the following keys: invoice_id, invnumber, invoice_date, amount, discount, and due. .Sp These are filtered based on the (required) properties: \&\f(CW$payment\fR\->{account_class}, \f(CW$payment\fR\->{business_type}, \f(CW$payment\fR\->{date_from}, \&\f(CW$payment\fR\->{date_to}, and \f(CW$payment\fR\->{ar_ap_accno}. .Sp The \f(CW$payment\fR\->{ar_ap_accno} property is used to filter out by \s-1AR\s0 or \s-1AP\s0 account. .Sp The following can also be optionally passed: \f(CW$payment\fR\->{batch_id}. If this is patched, vouchers in the current batch will be picked up as well. .Sp The returned list of hashrefs is stored in the \f(CW$payment\fR\->{contact} property. Each hashref has the following keys: id (entity id), name, and entity_class. .IP "list_open_projects" 4 .IX Item "list_open_projects" This method gets the current date attribute, and provides a list of open projects. The list is attached to \f(CW$self\fR\->{projects} and returned. .IP "list_departments" 4 .IX Item "list_departments" This method gets the type of document as a parameter, and provides a list of departments of the required type. The list is attached to \f(CW$self\fR\->{departments} and returned. .IP "list_open_vc" 4 .IX Item "list_open_vc" This method gets the type of vc (vendor or customer) as a parameter, and provides a list of departments of the required type. The list is attached to \f(CW$self\fR\->{departments} and returned. .IP "get_open_currencies" 4 .IX Item "get_open_currencies" This method gets a list of the open currencies inside the database, it requires that \&\f(CW$self\fR\->{account_class} (must be 1 or 2) exist to work. .Sp \&\s-1WARNING\s0 \s-1THIS\s0 \s-1IS\s0 \s-1NOT\s0 \s-1BEEING\s0 \s-1USED\s0 \s-1BY\s0 \s-1THE\s0 \s-1SINGLE\s0 \s-1PAYMENT\s0 \s-1SYSTEM\s0.... .IP "list_accounting" 4 .IX Item "list_accounting" This method lists all accounts that match the role specified in account_class property and are available to store the payment or receipts. =back .IP "list_overpayment_accounting" 4 .IX Item "list_overpayment_accounting" This method lists all accounts that match the role specified in account_class property and are available to store an overpayment / advanced payment / pre-payment. =back .IP "get_sources" 4 .IX Item "get_sources" This method builds all the possible sources of money, in the future it will look inside the \s-1DB\s0. =back .IP "get_exchange_rate(currency, date)" 4 .IX Item "get_exchange_rate(currency, date)" This method gets the exchange rate for the specified currency and date .IP "get_default_currency" 4 .IX Item "get_default_currency" This method gets the default currency =back .IP "get_current_date" 4 .IX Item "get_current_date" This method returns the system's current date .IP "get_vc_info" 4 .IX Item "get_vc_info" This method returns the contact informatino for a customer or vendor according to \&\f(CW$self\fR\->{account_class} .IP "get_payment_detail_data" 4 .IX Item "get_payment_detail_data" This method sets appropriate project, department, etc. fields. .IP "post_bulk" 4 .IX Item "post_bulk" This function posts the payments in bulk. Note that queue_payments is not a common setting and rather this provides a hook for an add-on. .Sp This \s-1API\s0 was developed early in 1.3 and is likely to change for better encapsulation. Currenty it uses the following structure: .Sp Within the main hashref: .RS 4 .IP "contact_count" 4 .IX Item "contact_count" The number of payments. One per contact. .IP "contact_$row" 4 .IX Item "contact_$row" for (1 .. contact_count), contact_$_ is the entity credit account's id associated with the current contact. We will call this \f(CW$contact_id\fR below. .Sp For each contact id, we have the following, suffixed with _$contact_id: .RS 4 .IP "source" 4 .IX Item "source" .PD 0 .IP "invoice_count" 4 .IX Item "invoice_count" .PD Number of invoices to loop through .IP "invoice_${contact_id}_$row" 4 .IX Item "invoice_${contact_id}_$row" for \f(CW$row\fR in (1 .. invoice_count), each this provides the transaction id of the invoice. .RE .RS 4 .Sp Each invoice has the following attributes, suffxed with ${invoice_id} .IP "amount" 4 .IX Item "amount" .PD 0 .IP "paid" 4 .IX Item "paid" .IP "net" 4 .IX Item "net" .RE .RS 4 .RE .RE .RS 4 .PD .Sp In the future the payment posting \s-1API\s0 will become more standardized and the conversion between flat and hierarchical representation will be moved to the workflow scripts. .RE .IP "check_job" 4 .IX Item "check_job" To be moved into payment_queue addon. .IP "post_payment" 4 .IX Item "post_payment" This method uses payment_post to store a payment (not a bulk payment) on the database. .IP "gather_printable_info" 4 .IX Item "gather_printable_info" This method retrieves all the payment related info needed to build a document and print it. \s-1IT\s0 \s-1IS\s0 \s-1NECESSARY\s0 \s-1TO\s0 \s-1ALREADY\s0 \s-1HAVE\s0 payment_id on \f(CW$self\fR .IP "get_open_overpayment_entities" 4 .IX Item "get_open_overpayment_entities" This method retrieves all the entities with the specified account_class which have unused overpayments .IP "get_unused_overpayments" 4 .IX Item "get_unused_overpayments" This is a simple wrapper around payment_get_unused_overpayments sql function. .IP "get_available_overpayment_amount" 4 .IX Item "get_available_overpayment_amount" Simple wrapper around payment_get_available_overpayment_amount sql function. .IP "init" 4 .IX Item "init" Initializes the num2text system .IP "num2text" 4 .IX Item "num2text" Translates numbers into words.