To create an instance app, the first step is to add it within your developer account. This allows you to specify the necessary URLs for turning the app on and off (needed for 4. Turn the app on in the app store and handling callbacks) and to generate OAuth credentials.
To complete the successful connection of the app and make successful API calls you will need to:
- Use the Authorization Code Grant flow and build the approval workflow to allow the user to log in and approve the app for connection. This generates the required access tokens for making successful API requests. Learn more about the authorization code grant flow.
- Use the tokens provided by the approval process to make authorized API calls.
How to add an app in your developer account
- Log into your developer account at https://developer.brightpearl.com/
- Click on New app.
- Enter the details of your app:
- Name - This is the name you will see in the app store.
- App reference - This is the reference your app is identified by.
- Short description - This description will be seen on the app in the app store.
- Long description - Record a more detailed description of your app.
- Type - Select Instance app. Do not use system and staff apps as support for these is being removed.
- Client type - This is the OAuth client type, select Confidential if your app is hosted/served on a private server. Select Public if your app is run on a device, e.g. a mobile phone app.
- User staff identity - When selected, changes in the Brightpearl account will be recorded as made by the user who approved/authorized the app.
- Payment type - Select Included with Brightpearl if users should be able to turn the app on without having to pay. Select Customer pays developer if you want to control who can turn the app on and direct them to contact you to subscribe before they can turn the app on. Read more about payments for apps
- Country restriction - Indicate which countries the app is available in. Read more about country restrictions below.
- Logo - Upload a logo for your app. This will display in the app store.
- Enter the URLs for your app:
- Redirect URI - (Mandatory) This is where the user will be redirected after approving/authorizing the app.
- Account install - (Optional) When the app is turned on, we will send an install callback to the URI you supply. Read more about handling callbacks
- Account uninstall - (Optional) When your app is turned off, we will send an uninstall callback to the URI you supply.
- User configuration - (Optional) This will be added as a link on the app store tile to help the user navigate to their configuration panel.
- User documentation - (Optional) This will be added as a link on the app store tile to help the user navigate to your help documentation.
- Healthcheck - (Optional) This will be added as a link on the app store tile to help the user navigate to any health check service you provide.
- Save the app and record your OAuth credentials in a secure place. You will not be able to view these details again so make sure you keep them safe.
- The Brightpearl support team will be alerted that you have added a new app and will approve it as soon as they can.
Most apps developed for Brightpearl will be ‘universal’ and available for any Brightpearl customer to install and use. Some types of app, typically those related to courier services, accountancy and taxation, are only relevant to customers in certain countries.
If you are developing an app which should only be made available to customers in particular countries, you will want to set up country restrictions on your app.
This can be defined when creating your app, but can also be changed at any time. By default the ‘Country restriction’ dropdown is set to ‘All countries’, which means any Brightpearl customer can find and install your app.
Restricting an app by country
An app can be restricted by using a whitelist or a blacklist:
- A whitelist allows only the mentioned countries to find and install the app. All other countries will be restricted from finding and installing it.
- A blacklist restricts only the mentioned countries from finding and installing the app. All other countries will be able to find and install it.
When adding a new app, select whitelist or blacklist as the restriction and then add the countries to approve/restrict.
Limitations and things to note
Brightpearl customers are free to choose their own country when creating a Brightpearl account and may change it at any time. You should be aware that:
- A customer may have set their country incorrectly.
- A customer may have previously had their country set to one which you allow, installed your app, then changed their country - this will not ‘uninstall’ your app for that customer.
- You might change your list of restricted countries to exclude customers who had previously installed your app - this will not ‘uninstall’ your app for that customer.
- Brightpearl accounts in South Africa use a non standard country code in their business address and cannot currently be whitelisted or blacklisted.