EzzyBills User Guide

EzzyBills API – Sample Applications in C#

The EzzyBills API supports both SOAP and REST endpoints. Below are some example programs.

I. Samples that use the EzzyBills  SOAP API

SOAP API Example 1: Upload an invoice to EzzyBills and get invoice data from EzzyBills

The following link contains a client program written in c# which uploads an invoice to EzzyBills, then waits for the workflow to complete. The invoice data is then printed out.

EzzyClient.zip

For example, the API call,

InvoiceBlocksSS ib = client.getInvoiceHeaderBlocks(invoice_id);

will return all invoice header data (total amount, tax, invoice date etc), as well as the Invoice table if it exists.

To use it,

  • Go to the www.ezzybills.com and click on Free Trial, then create a Trial account (use this username/pwd when running the program).
  • You may choose Xero as the accounting package to link to (go to https://www.xero.com/au/signup/ to setup a Xero trial account).
  • If you just want to extract the Invoice data (without exporting to an accounting system), then contact us and we will change your workflow. Before you execute the program you will need to add the API key (which we will email to you) to app.config file.

SOAP API Example 2: C# codes to read invoice lines data – resolving “tax inclusive” or “tax exclusive”

For invoice line data, the total can be either “”tax inclusive” or “tax exclusive”. You will need to read this status and act accordingly.

Below is the sample c++ codes for this purpose

switch (classification)
                {
                    case    
InvoiceEngine.invoiceclassification.UNIT_PRICE_INCLUSIVE_OF_TAX_AND_CHARGES_CHARGE_TAX_FREE:
                    case InvoiceEngine.invoiceclassification.UNIT_PRICE_INCLUSIVE_OF_TAX_AND_CHARGES:
                    case InvoiceEngine.invoiceclassification.GST_IN_TABLE_CHARGE_INCLUDES_GST:
                    case InvoiceEngine.invoiceclassification.GST_IN_TABLE_CHARGE_EXCLUDES_GST:
                    case InvoiceEngine.invoiceclassification.GST_IN_TABLE:
                    case InvoiceEngine.invoiceclassification.NO_TABLE:
                        {
                            line_amt_type = LineAmountTypes.Inclusive;
                            break;
                        }
                    case InvoiceEngine.invoiceclassification.HEADER_TABLE_NO_TABLE_VALIDATION:
                    case InvoiceEngine.invoiceclassification.HEADER_TABLE_TOTAL_ONLY_VALIDATION:
                        {
                            if (export_header_only || totalTax > 0)
                            {
                                line_amt_type = LineAmountTypes.Inclusive;
                            }
                            else
                            {
                                line_amt_type = LineAmountTypes.Exclusive;
                            }
                            break;
                        }
                    case InvoiceEngine.invoiceclassification.GST_NOT_IN_TABLE:
                    case InvoiceEngine.invoiceclassification.XERO_IMPORT:
                    case InvoiceEngine.invoiceclassification.CHARGE_INCLUDES_TAX:
                    default:
                        {
                            if (export_header_only)
                            {
                                //if header only then using the totals, which include tax.
                                line_amt_type = LineAmountTypes.Inclusive;
                            }
                            else
                            {
                                //this means the line item totals need to get adjusted, with the tax added.
                                line_amt_type = LineAmountTypes.Exclusive;
                            }
                            break;
                        }
                }

SOAP API Example 3: Add learning to an invoice

The following link contains a client program written in c# which adds learning to an invoice in Ezzybills. You must be the owner of this invoice to add learning to it:

LearningDemo.zip

The call made is:

client.addLearningRule(invoiceid, rule);

and the format for the learning rule is:

 LearningRule rule = new LearningRule()
 {
     supplierName = new LearningKeywordRule()
     {
         type = learningtype.keyword,
         keyword = "bills plumbing",
         position = keywordposition.UNKNOWN
     },
     locale = new LearningIntValue()
     {
         value = 0,
         specified = true
     },
     extra_keywords = new LearningExtraKeywords[]
     {
         new LearningExtraKeywords()
         {
             name = "keyword_gst",
             keywords = new string[] { "GST", "Tax" },
             weight = 8,
             position = 1
         },
         new LearningExtraKeywords()
         {
             name = "keyword_quantity",
             keywords = new string[] { "Freight" },
             weight = 6,
             position = 2
         }
     }
 };

SOAP API Example 4: Set Supplier and Purchase Order Data (for your EzzyBills account)

We also have a sample program which allows you to upload your vendor and purchase order data directly into EzzyBills. This information will be used when extracting the purchase order information off the invoice and when identifying the vendor. This is unnecessary when you use Ezzybills to inegrate with xero, Quickbooks or MYOB , however if you want to integrate with an ERP system which EzzyBills does not support then you should periodically load this information into your EzzyBills account.

EzzyClientLoad.zip

  for example,

 
 var csv = new CsvReader(new StreamReader(@"C:\ path to \PURCHASE_ORDERS.csv"));
 var poList = csv.GetRecords();
 ....

 var csv2 = new CsvReader(new StreamReader(@"C:\ path to \VENDOR_DETAILS.csv"));
 var vendorList = csv2.GetRecords();
 ....

 int rc = client.Login(user, pwd); // rc==1 indicates success

 //upload PPO info.
 client.addPurchaseOrders(po.ToArray(), exporttarget.XERO);
 
 //now lets upload the supplier info.
 client.addContacts(ven.ToArray(), exporttarget.XERO);

SOAP API Example 5: Converting Invoice to XML file

The following program will upload an invoice from your computer to EzzyBills then download the results as an XML file:

c:\>EzzyClientToXML.exe  frank blah taxinvoice.pdf
status=uploaded_invoice
Writing output file= 700411.xml

EzzyClientToXML.zip

  The output file will contain the invoice data. You can then extract this XML data and insert it into any Accounting package etc.

14601156281

0
0
Invoice
50.0000
2016-08-23T00:00:00
9922
550.0000


500.0000

BLAH

...


700411

OK

Annual subscription for EzzyBills- 6000 Invoices 0 0 44 0 1445 500.00 0





II. Samples that use the EzzyBills REST API

(or see REST API example using Postman) EzzyBills also supports a REST (JSON) API.

REST API Example 1: login to your  EzzyBills account and download the last 10 invoices processed.

RestClient client = new RestClient("https://app.ezzydoc.com/EzzyService.svc/");
client.AddDefaultParameter("APIKey", " add your API key"); //need to add your API key

RestRequest login = new RestRequest("/Rest/Login");

login.AddParameter("user", args[0]);
login.AddParameter("pwd", args[1]);
IRestResponse response = client.Execute(login);

CookieContainer cookiecon = new CookieContainer();
var cookie = response.Cookies.FirstOrDefault();
cookiecon.Add(new Cookie(cookie.Name, cookie.Value, cookie.Path, cookie.Domain));
client.CookieContainer = cookiecon;

RestRequest qdata = new RestRequest("/Rest/getMyInvoiceQueue?page=1&size=10&filter=Ordered"); //get the last 10 invoices
response = client.Execute(qdata);

REST API Example 2: upload the image (below is an example in c# you are probably using perl, objective or java)

    public class PictureFileSS
    {
        public string PictureName { get; set; }
        public byte[] PictureStream { get; set; }
    }

    class Program
    {
        static void Main(string[] args)
        {

            string APIKey = "api key";

            RestClient client = new RestClient("https://app.ezzydoc.com/EzzyService.svc/");
            client.AddDefaultParameter("APIKey", APIKey);   //need to add your API key

            RestRequest login = new RestRequest("/Rest/Login");

            login.AddParameter("user", "username");
            login.AddParameter("pwd", "password");


            IRestResponse response = client.Execute(login);
            Debug.Assert(response.StatusCode == HttpStatusCode.OK);
            int rc = JsonConvert.DeserializeObject(response.Content);
            if (rc != 1)
            {
                Console.WriteLine("login failed");
                return;
            }

            CookieContainer cookiecon = new CookieContainer();

            if (response.StatusCode == HttpStatusCode.OK)
            {
                var cookie = response.Cookies.FirstOrDefault();
                cookiecon.Add(new Cookie(cookie.Name, cookie.Value, cookie.Path, cookie.Domain));
            }
            client.CookieContainer = cookiecon;



            PictureFileSS pic = new PictureFileSS();
            pic.PictureName = "blah.pdf";

            FileStream fileStream = new FileStream(@"C:\temp\taxinvoice.pdf", FileMode.Open);

            MemoryStream mem2 = new MemoryStream();
            fileStream.CopyTo(mem2);
            pic.PictureStream = mem2.ToArray();


            DataContractJsonSerializer ser = new DataContractJsonSerializer(typeof(PictureFileSS));
            MemoryStream mem = new MemoryStream();
            ser.WriteObject(mem, pic);
            string data = Encoding.UTF8.GetString(mem.ToArray(), 0, (int)mem.Length);
            CookiedWebClient webClient = new CookiedWebClient();
            webClient.cookies = cookiecon;
            webClient.QueryString.Add("APIKey", APIKey);
            webClient.Headers["Content-type"] = "application/json";
            var ret = webClient.UploadString("https://app.ezzydoc.com/EzzyService.svc/Rest/uploadInvoiceImage", "POST", data);



        }
    }

REST API Example 3:  you can fetch the data back (will take 10-20 secs). The data returned would contain header info and table info (if it exists).

    public class InvoiceForm
    {

        public string ABNnumber { get; set; }
      
        public string supplierName { get; set; }
      
        public decimal chargeTotal { get; set; }
    
        public decimal discountTotal { get; set; }
     
        public decimal gstTotal { get; set; }
   
        public DateTime? invoiceDate { get; set; }
     
        public string invoiceNumber { get; set; }
  
        public decimal invoiceTotal { get; set; }
   
        public string purchaseOrder { get; set; }
    
        public string RefNumber { get; set; }
       
        public decimal subTotal { get; set; }
    
        public DateTime? paymentDate { get; set; }
      
        public string tag { get; set; }
      
    }


You can download more REST API sample here EzzyRestClient   Below is a trace traces showing you how EzzyBills expects messages to be formatted. To login you need to make a GET request with user, password and API Key in the query string. A cookie will be returned to you and you need to include this cookie in subsequent requests.  

The uploadInvoiceImage is a POST request and you need to add the API  key to the query string, include the cookie and add the JSON representation of the image to the body. The image data will be a bytes array (like shown below) . The invoice_id will get returned by this call. This id can be used to check that processing is complete and retrieve the invoice data.  

To get the extracted data you would make a GET request, pass in the API KEY along with the invoice_id (retrieved from the upload). 

 

REST API Example 4: Statement reconciliation with custom workflow

If you are using a custom workflow (i.e. integrating with a custom ERP system), then EzzyBills can still perform statement reconciliation provided you upload your invoice payment transactions. For example if you have a statement like below, and you want to determine which invoices have been paid, then you would use the API function /Rest/addInvoicePayment to upload the payment history from your ERP (see example code below). EzzyRestSR.zip    

You would then upload the statement via the EzzyBills SR App (Send email to: myname.App.SR@ezzybills.com ) . EzzyBills will then generate a report like below. Example Statement Reconciliation for SYDNEY DIRECT FRESH PRODUCE PTY LIMITED

INV#DescriptionStatusAmount(Stmt)Amount(Inv)LinkView
47188406/11/2018020.9520.95
#47390812/11/2018MISSING238.00
47695921/11/20180198.00198.00

REST API Example 5: switch user within HQ account

If you have a HQ account and you want to connect to multi users under the HQ account then you can use the switchUser API call

    Servicestatus switchUser(string name);

This call avoids you need to login to each individual account, which avoids you needing to store passwords and api keys for al your accounts

To use the code you first need to login to your HQ accounts

                string END_POINT = https://app.ezzydoc.com/EzzyService.svc/;
                RestClient client = new RestClient(END_POINT);

                RestRequest login = new RestRequest("/Rest/Login");
                login.AddParameter("APIKey", APIKey);   //need to add your API key
                login.AddParameter("user", args[0]);
                login.AddParameter("pwd", args[1]);


                IRestResponse response = client.Execute(login);
                Debug.Assert(response.StatusCode == HttpStatusCode.OK);
                int rc = JsonConvert.DeserializeObject<int>(response.Content);
                if (rc != 1)
                {
                    Console.WriteLine("login failed");
                    return;
                }

                CookieContainer cookiecon = new CookieContainer();

                if (response.StatusCode == HttpStatusCode.OK)
                {
                    var cookie = response.Cookies.FirstOrDefault();
                    cookiecon.Add(new Cookie(cookie.Name, cookie.Value, cookie.Path, cookie.Domain));
                }

                client.CookieContainer = cookiecon;

Then, you can switch to any account under your HQ account.

                    var request = new RestRequest("/Rest/switchUser?name=ezzymyob");
                    request.AddParameter("APIKey", APIKey);   
                    var response3 = client.Execute(request);
                    Debug.Assert(response3.StatusCode == HttpStatusCode.OK);

If you want to switch to another account then you first need to log back into the HQ account before switching (i.e. you can only switch if you are currently logged into the HQ account).

Because you will be making requests against multi-accounts you need to request a special API key which can be used for all your accounts (no need for a different key for each user).

Sections of Article