EzzyBills User Guide

Set up a free trial account to use EzzyBills API

You can use the API to integrate EzzyBills into your own custom workflows. For example if you want the invoice data extracted from the invoice and uploaded to your own ERP system then you can use the API.

Creating an EzzyBills account

To use the API you will need an EzzyBills account and an API KEY. Get an EzzyBills account by starting a Free Trial, and choosing to Integrate with any system listed, or if in doubt choose Custom (integrate via API)

You can create an API KEY in Settings > Advanced.

You will then need to add this key to you client application (for SOAP applications this will be in the app.config file, for REST applications this will be as a query parameter).


For example, the following code uploads an invoice to EzzyBills and then returns the Invoice Total, Tax etc.

Sample Application

   1:   class Program
   2:      {
   3:          static void Main(string[] args)
   4:          {
   5:  
   6:  
   7:  
   8:              if (args != null && args.Count() == 2)
   9:              {
  10:  
  11:                  EzzyServiceClient client = new EzzyServiceClient();
  12:  
  13:                  string user = args[0];
  14:                  string pwd = args[1];
  15:                  int rc = client.Login(user, pwd);  // rc==1 indicates success
  16:  
  17:                  string filename = @"taxinvoice.pdf";
  18:                  byte[] fileBytes = File.ReadAllBytes(filename);
  19:  
  20:  
  21:  
  22:                  PictureFileSS pf = new PictureFileSS() { PictureName = filename, PictureStream = fileBytes };
  23:  
  24:  
  25:                  uploadStatusSS us = client.uploadInvoiceImage(pf, documenttypes.Invoice, "blah");
  26:                  Debug.Assert(us.service_status.status == servicestatus1.OK);
  27:                  Debug.Assert(us.invoice_id > 0); // you can also get back the unique id for doc
  28:  
  29:                  int invoice_id = us.invoice_id;
  30:  
  31:                  while (true)
  32:                  {
  33:  
  34:                      WorkflowStatusSS ws = client.workflowStatus(invoice_id);
  35:  
  36:                          if (ws.complete)
  37:                          {
  38:  
  39:                              if (ws.children.Count() > 0)
  40:                              {
  41:                                  //document was autoseperated. iterate to get all child docs.
  42:  
  43:                              }
  44:                              break; //workflow complete
  45:                          }
  46:                      Console.WriteLine("status=" + ws.state);
  47:                      Thread.Sleep(1000);
  48:                  }
  49:  
  50:                  //now less get the data
  51:  
  52:                  InvoiceBlocksSS ib = client.getInvoiceHeaderBlocks(invoice_id);
  53:                  InvoiceBlocksSS ib_all = client.getAllInvoiceBlocks(invoice_id);
  54:  
  55:                  Console.WriteLine("Tax= " + ib.invoiceForm.gstTotal);
  56:                  Console.WriteLine("Total= " + ib.invoiceForm.invoiceTotal);
  57:                  client.Close();
  58:              }
  59:          }
  60:      }
            

WebHooks

There are two ways to know when an invoices workflow is complete. You can  poll the EzzyBills service or you can register a WebHook and be notified. To Register a WebHook, login to your EzzyBills account and in Advanced Options, add a URL to a web method (for example https://webhook.site ).

After you save the Webhook, you will receive a Token. This Token will get get sent with every WebHook call (you can use this to validate the call).

Once you have registered a WebHook, EzzyBills will call the Webhook every time the invoices workflow completes.

The WebHook call will contain the following information

  • parentid – if the original document was auto-separated then the parentid will contain the original docid.
  • docid – the docid of the invoice.
  • state – the state (26=success).
  • token – the WebHook validation token.

Example,

https://webhook.site/f77f11d5-d83a-4658-aeab-d83c53b4003d?docid=344131&parentid=0&state=26&token=b1e2ed24-f559-435b-ba71-83ad53e46c5d

This means that the document 344131 has successfully completed, it does not have a parent (i.e. no auto-separation).So you can now call getInvoiceHeaderBlocks(344131) to retrieve the invoice data.

Sections of Article