bigcommerce-oauth-api
This gem provides a wrapper for the Bigcommerce REST API.
Installation
You can install this gem by using the following command:
gem install bigcommerce-oauth-api
or by adding the the following line to your Gemfile.
gem 'bigcommerce-oauth-api'
Configuration
The gem can be configured either by module or class configuration. Starting from v1.2.0 bigcommerce-oauth-api
supports both OAuth and legacy authentication.
# module oauth configuration
BigcommerceOAuthAPI.configuration do |config|
config.store_hash = 'YOU STORE ID'
config.client_id = 'YOUR CLIENT ID'
config.access_token = 'YOUR OAUTH ACCESS TOKEN'
end
# module legacy (basic auth) configuration
BigcommerceOAuthAPI.configuration do |config|
config.endpoint = 'YOU STORE URL (https://store-XYZ.mybigcommerce.com)'
config.user_name = 'API USER NAME'
config.api_key = 'API KEY'
end
# class oauth configuration
api = BigcommerceOAuthAPI::Client.new(
:store_hash => 'YOUR STORE ID',
:client_id => 'YOUR CLIENT ID',
:access_token => 'YOUR OAUTH ACCESS TOKEN'
)
# class legacy (basic auth) configuration
api = BigcommerceOAuthAPI::Client.new(
:endpoint => 'YOU STORE URL (ex. https://store-XYZ.mybigcommerce.com)',
:user_name => 'API USER NAME',
:api_key => 'API KEY'
)
Starting from v1.2.1 bigcommerce-oauth-api
supports the If-Modified-Since
header described on https://developer.bigcommerce.com/api/req-headers. As all other configurations, the header can be set with both module and instance configuration using the key if_modified_since
.
Starting from v1.3.0 bigcommerce-oauth-api
allows you to opt-out of using BigcommerceOAuthAPI::Resource
through the typecast_to_resource
configuration. Setting this configuration to false
ensures that any response object will be of type Hash
instead of BigcommerceOAuthAPI::Resource
.
Using the API
It is recommended to use this documentation in combination the official api documentation on https://developer.bigcommerce.com/api/
Get a list of products:
products = api.products
Get orders with order_id >= 100
orders = api.orders({ min_id: 100 })
Get the order with id = 101
order = api.order(101)
All resource attributes can be accessed both using methods or as a hash with keys as either strings or symbols.
# each of the following lines return the first name listed in the order billing address
order.billing_address.first_name
order['billing_address']['first_name']
order[:billing_address][:first_name]
Update the name of a customer
customer = api.update_customer(101, {first_name: 'Christian'})
Delete an order shipment
order_id = 101
shipment_id = 1000
api.delete_order_shipment(order_id, shipment_id)
Webhooks
In many applications it is an advantage to receive a callback on events rather than polling information. Such callbacks are commonly called webhooks.
The Bigcommerce API allows you to create webhooks for events you want to respond to - for instance every time an order is created.
# more information on: https://developer.bigcommerce.com/api/webhooks-getting-started
new_hook = {
scope: "store/order/created",
destination: "https://app.example.com/order-callback",
is_active: true
}
hook = api.create_hook(new_hook)
After creating the webhook as shown above a callback (POST) will be sent to 'https://app.example.com/order-callback' every time an order is created.
The API also allows you to mange hooks like so:
# get a list of the webhooks
hooks = api.hooks
# get the webhook with id = 1234
hook_id = 1234
hook = api.hook(hook_id)
# delete the webhook with id = 1234
api.delete_hook(hook_id)
API Support
The following APIs are currently supported:
Getting an OAuth Access Token
The Bigcommerce API focused on making OAuth available for 3rd party development through Apps. Bigcommerce currently recommends using basic authentication when developing custom (private) integrations for your webshop.
However, it is actually possible to aquire access tokens without publishing an App for Bigcommerce by following these steps:
Login with the same user as the webshop you want to create a token for.
Go to "My Apps" and create dummy app (maybe call it "Authentication App")
Select the APIs you need and set the Auth Callback Url.
- This needs to be a HTTPS Url where you can read incomming GET request
Go to your webshop and click on "Apps"
Select the tab "My Drafts" (which should contain your "Authentication App")
Install the "Authentication App" in your webshop.
- This triggers a callback to your "Auth Callback Url" where you receive a code which can be exchanged for a token.
Send a POST request containing the following parameters (to https://login.bigcommerce.com/oauth2/token):
- client_id (can be found under "My Apps" at developer.bigcommerce.com
- client_secret (can be found under "My Apps" at developer.bigcommerce.com
- code (is received in the "Auth Callback")
- scope (is received in the "Auth Callback")
- grant_type (is always authorization_code)
- redirect_uri (your "Auth Callback Url")
- context (is "stores/store hash / id")
Done! The response returns your OAuth Access Token.
If you are experiencing problems with the POST call try using the folllowing curl command
curl --data "[YOUR POST PARAMETERS]" https://login.bigcommerce.com/oauth2/token