Developers

REST API

BluSynergy 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.

 

GENERAL APPROACH

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

RESTful Web Service HTTP methods

Content Negotiation – BluBilling 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).

Retrieve Examples (HTTP GET)

 

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.

Create Examples (HTTP POST)

 

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 BluBilling there is not a significant need for bulk updates, so only individual objects (along with their child objects) may be updated.

Update Examples (HTTP PUT)

 

Delete Examples (HTTP DELETE):

Delete operations are specified by id and in some cases by the unique business key. Currently, bulk deleted are not supported.

Delete Examples (HTTP DELETE)

 

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.

Complex-Cases-(HTTP-POST)

 

SECURITY

Authentication

Since the entire application will be restricted to HTTPS, the use of basic authentication in conjunction with the Spring Security (aka Acegi security) is used for BluBilling. This implies that all REST requests will be stateless.

 

Authorization

Authorization will be performed by requiring a security role called “ROLE_API”. Controllers will enforce that any REST request (format=xml) is served only if the caller is in the ROLE_API. 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 standard approach of using the DNS domain prefix (eg: acme.blubilling.com) will ensure that the requested operation pertains to objects owned by the appropriate “tenant” (i.e., Organization is the case of BluBilling).

 

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:

Sending malformed XML payloads

 

Whereas a validation error will produce these types of response:

Validation Error

MORE INFORMATION

iFRAME INTEGRATIONS

Hosted self-service pages allow you to embed the “My Account” functionality from BluBilling into your own website. This allows your customers to perform self-service activities such as view their account balances and status, current and past invoices, make payments, etc. All of these self-service screens are already built into BluBilling, and may be quickly deployed within a framed page on your own website so that you maintain brand presence with your customer by keeping them on your own website.

 

There are two approaches for deploying the BluSynergy Self-Service Portal inside your website:

  • Single Sign On (SSO) Option – In this model, your customers have already logged on to your application/website using a set of credentials that is managed outside BluSynergy. Your application/website handles the authentication of the customer, and makes an API call to indicate the particular customer for whom the self-service portal is to be shown.
  • BluSynergy Login Option – In this model your customers login using their BluSynergy userid and password. This greatly simplifies the integration, and no API calls are required. Simply create a iframe on your webpage and set the iframe source to https://yourcompany.blubilling.com/widget/login.

 

MORE INFORMATION

PUSH NOTIFICATIONS

Webhooks (also known as “web callbacks” or “outbound push notifications”) are sent by the BluSynergy system when specific business events occur. These are typically used when your application needs to be notified that billing or payments related events have occurred. These settings may be configured from the [System >> Integration Settings >> Website Callbacks] menu.

 

For example, let’s say you’d like to automatically provision a user account in your application/systems when a new customer is created and you’d like to de-provision/suspend the account if a customer is delinquent. In this case, you’d select the “New Customer Signup” and the “Customer Status Change” events. Now, all subsequent customer signups and customer status changes will cause the BluSynergy system to initiate a Webhook request to your system.

 

MORE INFORMATION