Application Programming Interface

webERP API - Getting Started

The API is an Application Program Interface, that is intended to expose webERP functionality to external programs. There are currently a number of low level functions it exposes to enable external applications to retrieve webERP data and to update or insert webERP data.

The API in webERP uses XML-RPC in particular the phpxmlrpc class from Useful Inc originally developed by Edd Dumbill

XML-RPC is a protocl to use XML to make RPC - remote procedure calls.

Simply put the XML-RPC call is XML that contains the method of the remote procedure call together with any parameters and their data types and is sent over http as a POST to the XML-RPC server - the server returns an XML payload containing the results of the call. The parameters sent to the methods can contain arrays and associative arrays of data.

The clever thing about XML-RPC is that it is the simplest protocol around for doing web-services. The newer and MUCH more complex SOAP - Simple Object Access Protocol - is quite involved and complicated. webERP is founded on the KISS principle.

In fact the XML-RPC "Server" in webERP is just the script http://www.yourdomain.com/webERP/api/api_xml-rpc.php

There is no daemon background process running continuously to field calls to the "server" it is just a script that is http posted to by the XML-RPC call sending the XML encoded method to be run together with the necessary parameters to the webERP API - the server script runs the API php functions exposed by the xml-rpc methods and returns the XML-RPC response as an XML payload. The phpxmlrpc class does the packaging converting the PHP variables and arrays to the XML required for the XML-RPC call and also has the functions to convert the XML response into something useable in PHP without having to write the XML parsing routines.

It is worthwhile reading a how-to on XML-RPC with PHP which explains in more detail what is going on as a primer for the concepts.

The beauty of XML-RPC is that the client calling the webERP XML-RPC server and performing native webERP functions can be called from any language (with XML-RPC bindings). I have used Vala, Genie and Python. Python particularly has been very straight forward as it has an xmlrpclib bundled with it. Of course a PHP client is also possible and is demonstrated below.

The API help is actually produced by an xml-rpc call to the API using the system.listMethods method (this is a phpxmlrpc method - not a webERP API method). Aother system xml-rpc method of phpxmlrpc class is used to return the details of each method's parameters required. So the help file not only documents each of the API methods it is itself and illustration of how the API can be used!!

Below is a simple example of how to use the API.

---

echo "Test webERP API";

//the xmlrpc class can output some funny warnings so make sure notices are turned off error_reporting (E_ALL & ~E_NOTICE);

/*you need to include the phpxmlrpc class - see link above - copy the whole directory structure of the class over to your client application from the webERP/xmlrpc directory */

include ("xmlrpc/lib/xmlrpc.inc");

//if your webERP install is on a server at http://www.yourdomain.com/webERP

$ServerURL = "http://www.yourdomain.com/webERP/api/api_xml-rpc.php";

$DebugLevel = 0; //Set to 0,1, or 2 with 2 being the highest level of debug info

$Parameters = array();

/*The trap for me was that each parameter needs to be run through xmlrpcval() - to create the necessary xml required for the rpc call if one of the parameters required is an array then it needs to be processing into xml for the rpc call through php_xmlrpc_encode()*/

$Parameters['StockID'] = xmlrpcval('DVD-TOPGUN'); //the stockid of the item we wish to know the balance for

//assuming the demo username and password will work !

$Parameters['Username'] = xmlrpcval('admin');

$Parameters['Password'] = xmlrpcval('weberp');

$msg = new xmlrpcmsg("weberp.xmlrpc_GetStockBalance", $Parameters);

$client = new xmlrpc_client($ServerURL);

$client->setDebug($DebugLevel);

$response = $client->send($msg);

$answer = php_xmlrpc_decode($response->value());

if ($answer[0]!=0){ //then the API returned some errors need to figure out what went wrong

//need to figure out how to return all the error descriptions associated with the codes

} else { //all went well the returned data is in $answer[1]

//answer will be an array of the locations and quantity on hand for DVD_TOPGUN so we need to run through the array to print out

for ($i=0; $i < sizeof($answer[1]);$i++) {

echo '
' . $answer[1][$i]['loccode'] . ' has ' . $answer[1][$i]['quantity'] . ' on hand';

}

echo "";

---

It is necessary to be logged in to see the API functions manual shows all the functions in the API with a description of the parameters required and what each function does.

To create invoices in webERP you need to use the following methods:

InsertOrderHeader InsertOrderLine - potentially multiple times for all the lines on the order then InvoiceSalesOrder - to invoice sales orders directly assuming the entire order is delivered - it cannot deal with controlled stock items though. However, it does process invoices in much the same way as standard webERP with updates to the stock quantities dispatched, GL entries and records required to record taxes and sales analysis records.

To create a credit note just a sinlge API call is required:
CreateCreditNote - to create a credit note from some base header data and an array of line items (as an associative array. In the same way as the InvoiceSalesOrder function this does all the same processing as a standard credit note from the interface in webERP.

There are some example scripts on the wiki showing how a number of the API XML-RPC functions are called - these scripts should be put on a web-server outside a webERP installation - all you need to do is edit the config.inc file to give the system your webERP username and password and the URL of your webERP installation you wish to connect to. As always playing with the examples helps to figure out how it all works.