Shoptet
This is Ruby API wrapper for Shoptet API which provides access to e-shop data for addon developers.
How to install
Currently only through Github:
gem 'shoptet', github: 'Masa331/shoptet'
How to use
Setup
First instantiate Shoptet which then represents connection to one specific shop
api = Shoptet.new(oauth_url, oauth_token, api_token, on_token_error)
And now you can access the data
api.price_lists
# => returns Enumerator with all price lists
params for ::new
* oauth_url
string with the oauth url for the partner shop under which is the addon registered.
oauth_token
string or nil with oauth token(the one you get during addon instalation process) used for creating api tokens. This gem can function without it but isn't able to auto re-create api tokens when necessary then.
api_token
string or nil with api token for accessing actual data. If it's not provided or is expired then this gem will request new one with the provided oauth token.
on_token_error
proc with what happens when missing or expired api token is encountered. If it's not provided then the default behaviour is to request new api token and store and use the new token only in api instance. The default proc looks like this
DEFAULT_ON_TOKEN_ERROR = -> (api) do
api.api_token = api.new_api_token
end
Custom proc can be used to add some special logic for this event like for example storing the new token also somewhere in the databse. The proc will be called with the api instance.
For the common scenario when working with Rails and ActiveRecord this gem also provides proc which stores the new token in ActiveRecord model. The proc can be instantiated like this Shoptet.ar_on_token_error(my_model_instance)
and expects the model to have #api_token
setter defined. The exact behaviour can be seen in the code.
Parallel requests
This gem fires only one network request at a time(of course) so some paralelization or whatnot is up to you.
Exceptions
This gem fires special exceptions on various events.
Shoptet::Error
when some general error occurs
Shoptet::AddonSuspended
when you are trying to access api for shop which has your addon suspended
Shoptet::NoRights
when you try to access api endpoint which is not approved
Shoptet::SlowDown
when 429 is returned from the api
Shoptet::InvalidOauthToken
when invalid oauth token is used
Collection endpoints
Methods for accessing collections(products, orders, ...) automatically handle pagination so you don't have to do it manually. These collection methods return instances of Enumerator
on which you can run standard methods like #each
, #map
, etc.
Also they accept hash with params which will be passed to Shoptet api. Through this you can set various filters and pagination.
Shoptet#products(api_params: {})
Shoptet#products_changes(api_params: {})
Shoptet#supplies(api_params: {})
Shoptet#product_categories(api_params: {})
Shoptet#price_lists(api_params: {})
Detail endpoints
Shoptet#product(guid)
Shoptet#order(code)
Other
Shoptet#new_api_token
- this returns new api token created with oauth tokenShoptet::install
- TODO
License
The gem is available as open source under the terms of the MIT License.