eBill API for Developers

REST Web Service API for eBill

Introduction

The BluSynergy eBill suite offers a contemporary REST based API that is agnostic of any programming language or operating system. Please refer to these three introductory sections about general usage patterns and programming practices before commencing development. Skip to the bottom of this page, to get to the API calls organized by business entity.

1.General Approach

The established conventions with regard to the HTTP verbs is shown below. 

Table 1.1 - RESTful web service mapping [2]

Content Negotiation - eBill will use a "format" request parameter to indicate the format. In the future, this may be extended to the ACCEPT or CONTENT_TYPE HTTP headers as well. The ContentType will be set appropriately (application/pdf, text/xml, etc.) by the application for the return.

Retrieve Examples (HTTP GET):

Note that when a multiple entities are expected, the URL maps to the plural form (eg "invoices" with a "s" at the end)

Create Examples (HTTP POST):

Note that when a multiple entities are expected to be created in a single call, the URL maps to the plural form. Note that all calls are atomic from a transactional standpoint.

Update Examples (HTTP PUT):

In the case of an update, the payload needs to contain the entire object graph and not just the changed values. In the use cases for eBill there is not a significant need for bulk updates, so only individual objects (along with their child objects) may be updated.

Complex Cases (HTTP POST):

In cases where the desired operation is an action, the REST approach has its deficiencies (when compared to SOAP). These cases are handled by a POST operation with an "action" query string parameter to indicate the desired operation. Additional parameters required by the operation are passed in the XML request payload. The result of the operation may return one or more objects depending on a case-by-case basis.

2. Security

Authentication

eBill utilizes HTTP Basic Authentication for authenticating each API call. A specific "system user" must be created for each client application that will integrate with eBill. The userid and password for this system user can then be used when making the API call. Note that the eBill application is restricted to communicating using HTTPS with 256-bit SSL certificates, implying that all data including the userid and password are sent encrypted and secured.

Authorization

The application authorizes REST requests only if the security credentials associated with the caller is in the "Web Service Programmatic Access" security role. A new user may be created with this security role by using the "System >> Staff Members" menu. Be sure to set the security role on this screen to "Web Service Programmatic (API) Access"

Multi-tenancy

The established approach of using the DNS domain prefix (eg: yourcompany.blubilling.com) will ensure that the requested operation pertains to objects owned by the appropriate "tenant" (i.e., Organization). If you get a HTTP 401 (Unauthorized) return code in spite of using a valid userid/password, then chances are that you have provided an invalid domain/url when performing the API request. All API access is logged and monitored and repeated attempts to access or "scan" entities belonging to other organizations will result in suspension and deactivation of your account per the terms of service.

3. Error Payload

The error response is usually accompanied by HTTP status code of 400

Sending malformed XML payloads will usually result in this type of response:

<status>

 <success>false</success>

 <errors>

  <error>org.xml.sax.SAXParseException: Closing tag for <customer> not found</error>

  <error>Premature end of file.</error>

 </errors>

</status>

Whereas a validation error will produce these types of response:

<status>

 <success>false</success>

 <errors>

  <error>

    The paymentMethodDTO/paymentMethod/type element must be set to 

    either Cash, ACH, CreditCard or Check

  </error>

 </errors>

</status>