BluSynergy Developer APIs and Integrations
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.
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).
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 BluBilling there is not a significant need for bulk updates, so only individual objects (along with their child objects) may be updated.
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.
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.
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:
Whereas a validation error will produce these types of response:
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 bequickly deployed within a framed page on your own websiteso that you maintain brandpresencewith 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 toyourapplication/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.
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 whenyour applicationneeds 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 subsequentcustomer signups and customer status changeswill cause the BluSynergy system to initiate a Webhook request to your system.