The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
LedgerSMB-API-0.04a
River stage zero No dependents
++
/ LedgerSMB::API

NAME

LedgerSMB::API - Exposing the LedgerSMB API to Integrators!

VERSION

Version 0.04a

SYNOPSIS

    use LedgerSMB::API;

    my($myconfig,$lsmb) = LedgerSMB::API->new_lsmb($login_name)

Generally the methods offered here can be invoked in the form:

    my ${entity}_id = LedgerSMB::API->create_new_{entity}($myconfig,$lsmb,\%fields);

Such create_new_ methods exist so far for entities: vendor, customer, part, assembly, order,

For accessors try:

    my ${entity}_id = LedgerSMB::API->id_existing_{entity}($class,$myconfig,$form,$fields);

Accessors now working for the following entities: vendor and customer.

And a key feature being direct access to the LedgerSMB database, using all the magic of DBI and DBD::Pg.

    my $dbh = $lsmb->{'dbh'};

    ...

CAVEAT

LedgerSMB is a recent fork of the SQL-Ledger codebase, developed by Dieter Simander. This module is being tested against LedgerSMB 1.2.9. LedgerSMB developers are warning of significant interface changes in upcoming development. These methods may or may not work using the pre-fork SQL-Ledger code. Testers, tests and patches to accomodate compatibility of the legacy code base are welcome. However currently developers are focused for the moment on simply exposing an API for the current stable version of the forked codebase.

The existing web interface offers a dizzying array of options you can set for an order, a customer, an invoice, etc. The methods offered here screen incoming data for legal field names and pass user values without validation, straight into the database using the save() routines offered by the LedgerSMB code base.

CAVEAT EMPTOR: These routines pass data, WITHOUT VALIDATION, straight into your accounting database. This means the user is responsible for cleaning their data and protecting the integrity of their accounting database. As this module is in its early phases of its development, folks are urged to test this code against COPIES of their existing set of real books and to report anomolies observed in their access and use of automated data in comparison with data entered through the more mature web interface.

Study the test suite for clues about how to use these methods to integrate an existing ecommerce application with LedgerSMB, permitting your ecommerce application to communicate with your accounting system. Help us test and develop this. Thanks.

METHODS

The following functions are available so far:

* new_lsmb() * create_new_vendor() * id_existing_vendor() * create_new_customer() * id_existing_customer() * create_new_part() * create_new_assembly() * create_new_purchase_order() * generate_invoice_from_purchase_order() * create_new_sales_order()

The following functions are priority for coming development now:

* generate_invoice_from_sales_order() * post_payment_to_ap_invoice() * post_payment_to_ar_invoice() * generate_account_statement()

my ($myconfig,$lsmb) = LedgerSMB::API->new_lsmb($login_name)

This initiates a connection to the LedgerSMB database and to its configuration as the user passed as an argument on invocation. This method returns a configuration hash and a LedgerSMB Form object, including access to its database handle and to the 68 methods made available by the LedgerSMB::Form module.

LedgerSMB::API->create_new_{entity}() functions generally

These methods, except as noted below, generally accept a $myconfig object, a $form object and a $fields hashreference on its interface. For each field name valid in the creation of the entity in the LedgerSMB system, the value associated with that key in the incoming $fields hash is encoded and assigned to an $entity object, and then the $entity object is used to create a new entity in the accounting system. If the 'taxable' key is set to a true value, the values for 'tax_account_field_name', 'tax_account_field_value' and 'taxaccounts' are used to indicate how the entity ought to be taxed.

For entities with multiple line numbers, like orders or invoices, assemblies, or even parts (from multiple vendors at various prices), field names will be in the form of fieldname_n, with n indicating the line number for the invoice.

It is generally possible to create valid entities in the accounting system populating only a fraction of the available fields.

my $customer_id = LedgerSMB::API->create_new_customer($myconfig,$lsmb,\%fields);

Valid keys for the %fields hash include: customernumber, name, address1, address2, city, state, zipcode, country, contact, phone, fax, email, cc, none, shiptoname, shiptoaddress1, shiptoaddress2, shiptocity, shiptostate, shiptozipcode, shiptocountry, shiptocontact, shiptophone, shiptofax, shiptoemail, taxincluded, startdate, enddate, creditlimit, terms, discount, taxnumber, sic_code, bic, iban, curr, employee, notes, taxable, tax_account_field_name and tax_account_field_value.

my $vendor_id = LedgerSMB::API->create_new_vendor($myconfig,$lsmb,\%fields);

Valid keys for the %fields hash include: vendornumber, name, address1, address2, city, state, zipcode, country, contact, phone, fax, email, cc, bcc, none, shiptoname, shiptoaddress1, shiptoaddress2, shiptocity, shiptostate, shiptozipcode, shiptocountry, shiptocontact, shiptophone, shiptofax, shiptoemail, taxincluded, startdate, enddate, creditlimit, terms, discount, taxnumber, gifi_accno, sic_code, bic, iban, curr, notes, action, id, taxaccounts, path, login, sessionid, callback and db.

my $part_id = LedgerSMB::API->create_new_part($myconfig,$lsmb,\%fields);

Valid keys for the %fields hash include: id, item, title, makemodel, alternate, onhand, orphaned, taxaccounts, rowcount, baseassembly, project_id, partnumber, description, IC_inventory, selectIC, IC_income, selectIC_income, IC_expense, selectIC_expense, notes, priceupdate, sellprice, listprice, lastcost, markup, oldmarkup, avgcost, unit, weight, weightunit, rop, bin, image, microfiche, drawing, selectvendor, selectcurrency, selectcustomer, selectpricegroup, customer_rows, makemodel_rows, vendor_rows, login, path, sessionid, callback, previousform, isassemblyitem.

Plus the IC_tax_nnnn and IC_tax_nnnn_description.

The price matrix for a part for each line number n, uses fields in the form: make_n, model_n, vendor_n, partnumber_n, lastcost_n, vendorcurr_n, leadtime_n, customer_n, pricebreak_n, customerprice_n, customercurr_n, validfrom_n and validto_n.

my $assembly_id = LedgerSMB::API->create_new_assembly($myconfig,$lsmb,\%fields);

my $purchase_order_id = LedgerSMB::API->create_new_purchase_order($myconfig,$lsmb,\%fields);

Valid keys for your %fields hash include: id, type, formname, media, format, printed, emailed, queued, vc, title, discount, creditlimit, creditremaining, tradediscount, business, recurring, shiptoname, shiptoaddress1, shiptoaddress2, shiptocity, shiptostate, shiptozipcode, shiptocountry, shiptocontact, shiptophone, shiptofax, shiptoemail, message, email, subject, cc, bcc, taxaccounts, audittrail, oldcurrency, selectpartsgroup, selectprojectnumber, oldinvtotal, oldtotalpaid, vendor_id, oldvendor, selectcurrency, defaultcurrency, forex, vendor, selectvendor, currency, shippingpoint, shipvia, employee, quonumber, oldtransdate, ordnumber, transdate, reqdate, ponumber, terms, notes, intnotes, formname, selectformname, format, selectformat, media, copies, groupprojectnumber, grouppartsgroup, sortby, action, rowcount, callback, path, login and sessionid.

For populating each line item, n, of your purchase order, the following fields are available: runningnumber_n, partnumber_n, description_n, qty_n, ship_n, unit_n, sellprice_n, discount_n, reqdate_n, notes_n, serialnumber_n, oldqty_n, orderitems_id_n, id_n, bin_n, weight_n, listprice_n, lastcost_n, taxaccounts_n, pricematrix_n, sku_n, onhand_n, assembly_n, inventory_accno_id_n, income_accno_id_n and expense_accno_id_n.

->generate_invoice_from_purchase_order()

Vaild keys include: id, type, formname, media, format, printed, emailed, queued, vc, title, discount, creditlimit, creditremaining, tradediscount, business, recurring, shiptoname, shiptoaddress1, shiptoaddress2, shiptocity, shiptostate, shiptozipcode, shiptocountry, shiptocontact, shiptophone, shiptofax, shiptoemail, message, email, subject, cc, bcc, taxaccounts, audittrail, oldcurrency, selectpartsgroup, selectprojectnumber, oldinvtotal, oldtotalpaid, vendor_id, oldvendor, selectcurrency, defaultcurrency, forex, vendor, selectvendor, currency, shippingpoint, shipvia, employee, quonumber, oldtransdate, closed, closed, ordnumber, transdate, reqdate, ponumber, terms, notes, intnotes, formname, selectformname, format, selectformat, media, copies, groupprojectnumber, grouppartsgroup, sortby, action, rowcount, callback, path, login, sessionid,

Valid keys for each line item include: oldqty_, orderitems_id_, id_, bin_, weight_, listprice_, lastcost_, taxaccounts_, pricematrix_, sku_, onhand_, assembly_, inventory_accno_id_, income_accno_id_, expense_accno_id_, runningnumber_, partnumber_, description_, qty_, ship_, unit_, sellprice_, discount_, reqdate_, notes_, serialnumber_,

my $result = LedgerSMB::API->post_payment_to_ap_invoice($myconfig,$lsmb,\%fields);

Valid fields include: id, title, vc, type, terms, creditlimit, creditremaining, closedto, locked, shipped, oldtransdate, recurring, selectcurrency, defaultcurrency, taxaccounts, audittrail, oldcurrency, selectpartsgroup, selectprojectnumber, vendor_id, oldvendor, selectAP, selectcurrency, defaultcurrency, forex, vendor, selectvendor, AP, currency, quonumber, invnumber, ordnumber, transdate, duedate, ponumber, notes, intnotes, import_text, cleared_1, paidaccounts, selectAP_paid, oldinvtotal, oldtotalpaid, action, rowcount, callback, path, login and sessionid.

The line items on a vendor invoice are described using these fields: oldqty_, orderitems_id_, id_, bin_, weight_, listprice_, lastcost_, taxaccounts_, pricematrix_, sku_, onhand_, assembly_, inventory_accno_id_, income_accno_id_, expense_accno_id_, runningnumber_, partnumber_, description_, qty_, unit_, sellprice_, discount_, deliverydate_, notes_, serialnumber_,

Payments on Vendor Invoices are made using these fields: datepaid_, source_, memo_, paid_ and AP_paid_.

my $sales_order_id = LedgerSMB::API->create_new_sales_order($myconfig,$lsmb,\%fields);

$customer_id = id_existing_customer($class,$myconfig,$form,$fields);

$vendor_id = id_existing_vendor($class,$myconfig,$form,$fields);

This is a simple comparison of email addresses and returns either 0, if no matches or the id for the requested vendor or customer. It is imagined that a more sophisticated duplicate matching routine will be written on an installation by installation basis over-riding this one.

AUTHOR

Nigel Titley and Hugh Esco, <nigel at titley.com and hesco@campaignfoundations.com>

KNOWN BUGS

create_new_assembly() broken

This routine currently can successfully create a record in the parts table, but fails to create one in the assembly table, as is done from the browser interface using the Goods_&_Services->Add_Assembly screen. As a consequence the new assembly created with this method is unavailable in the Goods_&_Services->Stock_Assembly screen.

Your bug reports welcome

Please report any bugs or feature requests to bug-ledgersmb-api at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LedgerSMB-API. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc LedgerSMB::API

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2009 Nigel Titley and Hugh Esco, all rights reserved.

This program is released under the following license: gpl