This page helps you understand what the Brightpearl API is all about. It's important to note that the Brightpearl system is effectively made of two parts; the "database" and the "web interface". You can access your database by two methods; via the web interface in a browser like Firefox, or direct to the database over API.
For technical API documentation, click here
What is an API?
An Application Programming Interface (API) is a set of messages that allow two separate computer systems to exchange data. For example, we use the Sagepay API to allow Brightpearl to connect to Sagepay’s systems and process payments. The Brightpearl API will allow external systems to access selected data stored in your account without using the web interface.
An API facilitates a ‘conversation’ between two systems, and you will often hear the terms ‘request’ and ‘response’. System A makes a request for information from System B; System B then sends a response with the requested information. A request-response pair is called a ‘message’
The most common use of an API is to extract data from a system, but an API can also be used to ‘invoke functionality’. This means System A asks System B to do something on its behalf, like send an invoice or move some stock between warehouses.
The term API predates the Internet, and used to refer to two parts of a single computer programme communicating with each other. When you make an API available over the Internet, the API is commonly referred to as a set of ‘web services’.
Whose API?
When Brightpearl integrates with third-party systems, like Sagepay and Mailchimp, we use their API. When you do something in the application via the web interface (such as adds a tag to a contact for email marketing), our system tells Mailchimp that something needs to be done.
In this scenario, Brightpearl is a ‘client’ of the Mailchimp API. We have to write software to communicate with their API.
If you, as a Brightpearl customer, want to work with information in your Brightpearl account, you need to use the Brightpearl API. If you want, you can build a system to talk to both APIs, a bit like an interpreter. Let's call this a connector:
Building a connector
This is where both parties in the integration (say Brightpearl and Amazon) present their API to a third-party developer to build a connector.
The connector software is hosted on some other server (i.e. neither Brighpearl's servers or Amazon's) and periodically contacts (or ‘polls’) both APIs to see if any new work needs to be done. This can be quite inefficient as you either have to poll frequently, causing work for both systems, or accept that some actions are not taken immediately.
Some APIs have the concept of "webhooks" or callbacks, which are messages used to poke the connector into action; for example "New order, come and get it". The Brightpearl API doesn't currently support webhooks, but we're working on it.
Brightpearl hosted integrations
There are some integrations that are so core to a business operation that they need to be embedded within the Brightpearl codebase. Examples of this are the Payment providers like SagePay, email marketing and SMS provision. In fact we're actually working on a design that allows you to build your own connectors and embed them within the Brightpearl interface, giving you the best of both worlds. That's a good few months away though, but it will be awesome when it's here.
Brightpearl API Concepts
The Brightpearl application makes use of a set of private web services (or just ‘services’), each of which performs a particular set of tasks. For example, the ‘warehouse’ service is responsible for stock control and product availability and the ‘order’ service is responsible for creating and managing sales orders. Breaking an application into a set of services is a common programming technique, and is called ‘Service Oriented Architecture’ or SOA.
The goal of the Brightpearl API is to give you direct access to exactly the same set of services that the Brightpearl application uses, but over the Internet and with additional security checks.
Resources
Entities in Brightpearl such as a Contact, Order, Product or ShippingMethod are called ‘resources’. Our API is designed so that other systems will achieve their goals by interacting with resources. Resources can created, updated, viewed and deleted.
Almost everything can be done using these messages, so for example changing the address of a warehouse is achieved by updating a Warehouse resource.
This technique is not unique to Brightpearl; it is actually following a standard for creating web service APIs called REST (Representational State Transfer, but everyone just says REST). There is a little bit of terminology that is worth knowing about REST:
To view some data is to GET a resource.
To create a brand new entity is to POST a resource.
To modify an existiting entity is to PUT a resource.
To remove an existing entity is to DELETE a resource.
What could I do with the API?
The idea of providing a public set of web services is that you can do anything that your imagination (and the messages) will support. We're driving the project with the intention of supporting the following kinds of integration first:
- Integrate a 3rd party eCommerce store like Shopify or Magento; create products in Brightpearl to see them appear on your eCommerce store, and as orders are placed on your store, they automatically appear in Brightpearl.
- Connect to a fulfilment / warehouse management service; as you create Goods-out notes in the application they can get picked up by a warehouse system for shipment. If you're on Premium stock you can mark the goods-out note as shipped, however on Standard or Basic plans you'd probably want to mark the order as updated; we don't have this message yet.
- Synchronise your Brightpearl contact database with another CRM system; you'd need to wait for our contact service to go live.
- Query contacts, add notes etc via an iPhone app; again you'd need our contact service for this.
- Enter expenses whilst on the road via a mobile app; you'd need various accounting services.
What's implemented so far?
So far, we've implemented the warehouse service, and are fleshing out some other messages with the goal of providing product based companies with integrations to other systems like eCommerce, fulfilment, warehouse etc.
What's coming up?
This is a very provisional list of the features we are planning to tackle, in the order that they will be released. It's important to note that this is not a formal roadmap, and may change.
May 2011
Updating stock levels and working with goods-in / goods-out
June 2011
GET products - for warehouse and eCommerce integrations
GET orders/invoices - required for most warehouse system integrations
July 2011
POST orders/invoices into Brightpearl - to integrate an eCommerce system
Orders - adding notes, changing status and other order meta data
Aug 2011
Working with products and services, including price lists - update items within Brightpearl
Sept 2011
Contacts
How do I get my requested API features prioritised?
We've got a Uservoice channel focussed exclusively on the API; if you'd like us to develop a message, please post it on our forum with an explanation of how you plan to use it.
Other API functionality not yet planned
These features will be available over API soon, but we haven't got a fixed date for you
- Tasks & Activities
- Tickets
- Accounting
- Setup (Create contact tags, statuses, ticket types etc)
