Utility messages

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
    }
  ]
}
 
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.