Brightpearl

The Brightpearl gem allows Ruby developers to access the Brightpearl API resources for instance confidential apps.

The Brightpearl API is implemented as a REST API JSON interface, using various HTTP verbs such as: GET/POST/PUT/PATCH/OPTIONS/DELETE. Each resource, like Order, Product, or Contact, has different operations available.

To read more, follow the link to the official documentation: https://api-docs.brightpearl.com/

Add this line to your application's Gemfile:

gem 'ruby-brightpearl'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install ruby-brightpearl

All API usage happens through brightpearl applications, created by developers for private usage or for use by other brightpearl site owners:

A brightpearl developer account is required to begin the development of apps, to read more info about the account creation refer to: https://help.brightpearl.com/hc/en-us/articles/211124886-Register-as-a-Brightpearl-developer

Once an account is provided, developers can create applications through the official portal of brightpearl applications: https://developer.brightpearl.com/

Using the official portal create a new application, the type must be instance, once the app has been created an "application ID" and "secret" should be provided.

Start by setting up the initial configuration for the client:

require 'brightpearl'

Brightpearl.config.account =      ACCOUNT # Account to request API access
Brightpearl.config.dev_ref =      DEV_REF # From developer account creation

Brightpearl.config.app_ref =      APP_REF # Brightpearl app ID
Brightpearl.config.app_secret =   APP_REF # Brightpearl app secret

Before the API calls can be performed you will need to get a token, to get one the authentication flow must be followed as per brightpearl documentation: https://help.brightpearl.com/hc/en-us/articles/360032240811-Set-up-the-Authorization-Code-Grant-flow

The oauth URL can be then generated with:

Brightpearl::Auth.oauth_url(state: "random-passcode", redirect_uri: "https://www.something.io/oauth") # => "https://oauth.brightpearl.com/authorize/testAccount?response_type=code&client_id=testAppName&redirect_uri=https://www.something.io/oauth&state=random-passcode

NOTE: The state argument on oauth_url method is a string defined by yourself, this should be a non guessable string that the authorization server will pass back to you on redirection which you should check against to prevent CSRF attacks

The oauth process will redirect to your redirect_uri with a param called code, the value of this parameter is a temporary token that the app can exchange for an access token.

This process be done by:

Brightpearl::Auth.request_token(auth_token: AUTH_TOKEN, redirect_uri: "https://www.something.io/oauth") # => { payload: { "access_token" => "XXX", "refresh_token" => "XYZ", "api_domain" => "ws-use.brightpearl.com" } }

After the token is obtained it can be added to client by setting it on the config:

Brightpearl.config.api_domain = API_DOMAIN # Such as ws-use.brightpearl.com
Brightpearl.config.token = TOKEN
Brightpearl.config.refresh_token = REFRESH_TOKEN

NOTES:

• The token has a expiration time, when the token has expired a new one can be obtained using a refresh token.
• The redirect_uri used on request_token should be the same used on oauth_url

When the token has expired, the use_refresh_token method can be used:

Brightpearl::Auth.use_refresh_token(refresh_token: "XXX")
# If refresh_token is loaded on config just call the method
Brightpearl::Auth.use_refresh_token()

The return value is the same as request_token, additionally by default the new token and refresh_token are loaded on Brightpearl.config, if for some reason this is undesired it can be turned off by calling the method as Brightpearl::Auth.use_refresh_token(autoupdate: false)

Responses to REST requests are parsed into a hash with the keys :payload with the actual response from brightpearl API and :quota_remaining with the value of the current quota.

NOTE: Search operations returns a Ruby object for the resource as well for easier access to the attributes, this is returned in the :records key on the result.

result = Brightpearl::Order.get(1)

order = result[:payload]["response"].first
puts order["id"] # => 1
puts order["orderTypeCode"] # => "SO"

Brightpearl API allows for multiple items to be requested at once on most resources:

product_ids = [1, 2, 3]
result = Brightpearl::Product.get(product_ids.join(","))
puts result[:payload]["response"].size # => 3

NOTE: For more information about brightpearl API syntax refer to: https://help.brightpearl.com/hc/en-us/articles/212645003-URI-syntax

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ruby-brightpearl. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Brightpearl project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.