This article explains the legacy method of creating private apps. The current recommended method of connecting to the API is to create an Instance app. If you want it to be private, you don't need to request progress through to publishing on the app store.
Read more about OAuth authentication
This is an introduction using Brightpearl API to extend a single Brightpearl account using a private app. A private app is added directly within the Brightpearl account.
To connect a private app to a Brightpearl account you will need to have the "settings" permissions for your user login to the Brightpearl account.
If you are interested in publishing an app on the App Store you must be a registered Brightpearl developer.
Please note that the Brightpearl API is intended to be used by experienced developers.
Set up a basic test environment
The API we make public is a subset of the API we use internally, so we would like to recommend some basic tools we use for connecting to and testing the API.
- Google Chrome
- Advanced REST client Application for Chrome - An excellent tool that we use in-house to test calls to our API.
- JSONView a Chrome extension which makes JSON responses from the API easier to read.
We also highly recommend the JetBrains family of IDEs (we use them here) and a copy of RESTful Web Services which had a very strong influence on the design of the Brightpearl API.
Base URI
Brightpearl accounts are hosted in several different data centres across the world. In order to connect to the correct data centre, you will need to know the correct base URI for your account. You can work this out by referring to our page on URI syntax but alternatively log in to your Brightpearl account and look at the domain name in your browser.
You can then refer to this table to determine your base URI:
Brightpearl domain name | Base URI |
---|---|
euw1.brightpearl.com | https://ws-eu1.brightpearl.com/public-api/{account-id} |
use1.brightpearl.com | https://ws-use.brightpearl.com/public-api/{account-id} |
So if your account is on the use data centre and has an account code of myaccount your base URI will be:
https://ws-use.brightpearl.com/public-api/myaccount
Advanced Rest Client
Start Chrome and open Advanced Rest Client by clicking on the Apps button (underneath the back button) and clicking on the blue Advanced Rest Client icon.
If you see any data in the text fields, press the ‘Clear’ button.
Sending your first request
In the URL text field, enter your base URI followed by /warehouse-service/warehouse (e.g. https://ws-use.brightpearl.com/public-api/myaccount/warehouse-service/warehouse).
This is the URI for a Warehouse GET request which will give you information about the warehouses set up on your Brightpearl account.
If you press the ‘Send’ button now, you will receive a ‘401 Unauthorized’ message. This is because access to individual accounts is tightly controlled. For more details, please read API authentication for private apps, but for now click on the ‘Form’ tab in Advanced Rest Client and add two headers brightpearl-app-ref and brightpearl-account-token
These should be set to the app ref you picked and token that was generated for you when you created your private app earlier.
You will end up with table in Advanced Rest Client which looks something like:
If you press ‘Send’ now you should get 200 OK response and a JSON message describing your warehouses.
Next steps
Congratulations! You have now connected to the Brightpearl API. Although Advanced Rest Client is a great tool for exploring the API, it is most likely that you will be using a programming language like Java or PHP to integrate your software with Brightpearl. Please read the API fundamentals section of our support documentation for some pointers on how to start building a real integration.