This article contains content which relates to our legacy authentication mechanism The account data center is no longer required for API calls - the api_domain is given by the OAuth mechanism.
The Brightpearl API provides a set of utility messages that provide meta-data about Brightpearl customer accounts which might have installed your app.
About Brightpearl datacentres
Brightpearl is a globally distributed application. Customer accounts are hosted in a number of datacentres around the world.
Our European datacentre (which we refer to as euw1) is considered our master datacentre. The datacentre in which a particular account is hosted is referred to as the account datacentre.
Authentication
To use the messages below you need to supply a single request header, brightpearl-dev-token with each request. The value of this header should be your developer token signed with your developer secret. The signing algorithm is the same as when you sign account tokens with your developer secret for the purpose of accessing customer account data
To test that your algorithm is correct, you can use this data for comparison:
| Unsigned developer token | MlcTe8zimMPgYf/batW+ckJEAj467bbapA0cQBx6WwM= |
| Developer secret | irhkVURWuLDYZwziDKhCsSGYrczWtfL7Pz5oX2GRDXo= |
| Expected result | llWnSJurpSUUTLNOtVd8Ik/ox6+4OVY/TdLSvE1+VWg= |
Discovering an account’s ‘account datacentre’
Before you can start accessing an account’s data, you need to know which datacentre it is hosted on so you can construct the correct URI for calls to the Brightpearl API.
Please note that this message needs to be called against the master datacentre.
URI Syntax
https://ws-eu1.brightpearl.com/developer-tools/{developer-ref}/account-location/{account-code
Example request
https://ws-eu1.brightpearl.com/developer-tools/test-dev/account-location/some-account GET
Example response
{
"response": {
"datacentreCode": "use1",
"apiDomain": "ws-use.brightpearl.com"
}
}Discovering an account’s time zone
Some apps need to know what ‘display’ time zone a Brightpearl account has been configured to use in order to present dates and times consistently with what the customer will see when using Brightpearl.
Please note that this information is only needed for display purposes. You should never use this data to try and calculate offsets for sending dates and times into the Brightpearl API. All Brightpearl API date-times are stored as UTC.
The time zone information is returned in two different forms: a canonical time zone ID (Europe/London, America/New_York etc) and the current offset of that time zone from UTC.
Canonical time zone IDs are compatible with most programming languages or date/time libraries (e.g. Joda for Java).
The offset from UTC is the current offset (e.g. it factors in daylight savings if appropriate)
The message should be sent to the account datacentre associated with the customer account.
URI Syntax
https://{account-datacentre}/developer-tools/{developer-ref}/account-timezone/{account-code}
Example request
https://ws-use.brightpearl.com/developer-tools/test-dev/account-timezone/some-account GET
Example response
{
"response": {
"canonicalId": "America/New_York",
"currentUtcOffset": "-04:00"
}
}Discovering who has installed your app
If you have not configured your app to support callbacks from Brightpearl, you will need a way of programmatically determining who has installed your app, what their public account tokens are, when they installed your app and whether it is enabled or disabled.
(Please note, we strongly recommend that you support callbacks from Brightpearl in all of your apps)
This message can be sent to any datacentre but we recommend you send it to the master datacentre.
URI Syntax
https://ws-eu1.brightpearl.com/developer-tools/{developer-ref}/installed-accounts/{app-ref}
Example request
https://ws-use.brightpearl.com/developer-tools/test-dev/installed-accounts/my-app-ref GET
Example response
{
"response": [
{
"installedOn": "2014-08-21T00:00:00.000Z",
"accountCode": "someaccount",
"unsignedAccountToken": "e073e3c7-129f-4bbe-bafb-dddd93ebd842",
"enabled": true
},
{
"installedOn": "2014-07-23T00:00:00.000Z",
"accountCode": "50fc9b6e-f179-4fd5-bb73-fef5b993782f",
"unsignedAccountToken": "asdasdasd",
"enabled": false
}
]
}