mercadolibre 0.0.9 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f8c16d0c18a6d1d9aea7b92e6ab7fe0ed0876388
-  data.tar.gz: 457995eab154f1cb315e42128e60e80c667dc1bf
+  metadata.gz: 19c27d08b54ebb86fc18958f21cb75149c99dbc7
+  data.tar.gz: 75c1ee72e514f505dd2890165424df01ba3fff03
 SHA512:
-  metadata.gz: db44a5bf89a710404d3efc7fc6ace79c194fc83294cfbf9d31f9dc9610e166307e27ea9ce939a4abeb3e31ca01fd579b1256318fbfe40960f7ec39bc4d0a5c01
-  data.tar.gz: 825f47d7da50a74313e3d319a0d3ed6db232b7a5a6c7893c03a32cc22004ea20836aa607c615b1464c4b10b0361d456b204212a668516bf5a08c34cb70701dc9
+  metadata.gz: 9600dc5c39d2fee08de877ab0ac8c7848352be0f171a1c47e5501d668464796af16ab01b80fc0f1431aa7a3c4f94d7038892f4b59d99adc6f9ee64508f11c411
+  data.tar.gz: 7c1c162e7b0889b5e219413dfa93ee3e1169d544ff6f34be55c8fd5284f2cd26d1e218f6dc6b95599680a966369c0b2d04c00dda2d6ce049a281d88071ae7f93

data/CHANGELOG.md

@@ -33,3 +33,7 @@
 ## v0.0.9
 
 * Implemented more methods from the API
+
+## v0.1.0
+
+* Improved documentation and little refactor

data/README.md

@@ -1,21 +1,273 @@
-# Mercadolibre
+Mercadolibre
+==============
 
-Implementation of meli API to access MercadoLibre
+Mercadolibre gem implements MELI API (Official API available to interact with Mercadolibre).
 
-## Installation
+It implements most of the methods of the official API and it makes it very easy to interact with.
 
-Add this line to your application's Gemfile:
+Requirements
+-----------------
 
-    gem 'mercadolibre'
+You need to create an application in http://applications.mercadolibre.com in order to get app key and app secret.
 
-And then execute:
+Rest Client is used to perform all API calls.
 
-    $ bundle
 
-Or install it yourself as:
+Installation
+-----------------
 
-    $ gem install mercadolibre
+    gem install mercadolibre
 
-## Usage
 
-TODO: Write usage instructions here
+Getting started
+-----------------
+
+MELI uses OAuth protocol for authentication, so you first need to get an access token.
+
+In order to do that you first need to instance the API:
+
+    api = Mercadolibre::Api.new({
+      app_key: 'YOUR_APP_KEY',
+      app_secret: 'YOUR_APP_SECRET',
+      callback_url: 'YOUR_CALLBACK_URL',
+      site: 'YOUR_SITE_COUNTRY'
+    })
+
+Site country is the site id for the country you are using (eg. Argentina's site id is MLA).
+
+In case you already have an access token, it could be passed directly in the constructor hash or it can be assigned through property 'access_token'.
+
+To get a url of mercadolibre authentication page you can call authenticate_url method:
+
+    # it returns the authentication page you should send user to
+    api.authenticate_url
+
+After authentication, you'll be redirected to callback url with an auth code (code variable from return url). With this code, you'll get access token (also refresh token in case you need it).
+
+    # auth_data (access_token, refresh_token, expired_at)
+    auth_data = api.authenticate(your_auth_code)
+
+As soon as you are authenticated and you have a valid access token, you are all set for using the API.
+
+
+API Methods
+-----------------
+
+##### Auth
+
+    * api.authenticate_url
+      -> Returns mercadolibre authentication url.
+
+    * api.authenticate(auth_code)
+      -> Returns authentication tokens with auth code provided in callback url.
+
+    * api.update_token(refresh_token)
+      -> Extends token expiration (useful to keep alive a token).
+
+##### Categories and listings
+
+    * api.get_sites
+      -> Returns all available sites.
+
+    * api.get_site(site_id)
+      -> Returns data of specific site.
+
+    * api.get_site_domain_info(domain)
+      -> Returns data of specific site domain (eg. mercadolibre.com.ar).
+
+    * api.get_listing_types(site_id)
+      -> Return all listing types available for the site.
+
+    * api.get_listing_exposures(site_id)
+      -> Return all listing exposures available for the site.
+
+    * api.get_listing_prices(filters)
+      -> Return all listing prices that matches with the given filters.
+         Possible filters are:
+         - price
+         - listing_type_id
+         - quantity
+         - category_id
+         - currency_id
+
+    * api.get_site_categories(site_id)
+      -> Returns main site categories.
+
+##### Items and searches
+
+    * api.get_all_my_item_ids(filters={})
+      -> Search all your item ids with filters (without pagination).
+
+    * api.get_my_item_ids(filters={})
+      -> Search all your item ids with filters (with pagination).
+
+    * api.get_all_item_ids(filters={})
+      -> Search all item ids with filters (without pagination).
+
+    * api.get_item_ids(filters={})
+      -> Search all item ids with filters (with pagination).
+
+    * api.get_item(item_id)
+      -> Gets item detail.
+
+    * api.get_item_visits(item_ids)
+      -> Gets items visits. If you provide an item id as a string you'll get an integer.
+         If you pass an array of item ids, you'll get a hash with the items visits for each.
+
+    * api.get_item_descriptions(item_id)
+      -> Gets all item descriptions from an item.
+
+    * api.get_item_available_upgrades(item_id)
+      -> Gets all available listing types for upgrade for the item.
+
+    * api.get_search_url(site_id, q)
+      -> Gets search url for the site and query.
+
+    * api.get_hot_items(site_id, category_id, limit=15)
+      -> Gets category hot items.
+
+    * api.get_featured_items(site_id, pool_id)
+      -> Gets featured items.
+
+    * api.get_site_trends(site_id, category_id)
+      -> Gets site trends for category.
+
+    * api.item_valid?(attribs)
+      -> Checks if attributes are valid for creating an item.
+
+    * api.create_item(attribs)
+      -> Creates an item.
+
+    * api.relist_item(item_id, price, quantity, listing_type_id)
+      -> Relists an item.
+
+    * api.update_item_fields(item_id, attribs)
+      -> Updates item fields (price, stock, etc).
+
+    * api.update_item_listing_type(item_id, listing_type_id)
+      -> Updates item listing type.
+
+    * api.add_item_description(item_id, text)
+      -> Adds description to item.
+
+##### Locations and currencies
+
+    * api.get_countries
+      -> Gets countries.
+
+    * api.get_country(country_id)
+      -> Gets country.
+
+    * api.get_state(state_id)
+      -> Gets state.
+
+    * api.get_city(city_id)
+      -> Gets city.
+
+    * api.get_currencies
+      -> Gets currencies
+
+    * api.get_currency(currency_id)
+      -> Gets currency info
+
+    * api.currency_convertion_rate(currency_from, currency_to)
+      -> Gets currency conversion rate
+
+    * api.get_zip_code_info(country_id, zip_code)
+      -> Gets zip code info
+
+##### Order management
+
+    * api.get_all_orders(filters={})
+      -> Get all orders with filters (without pagination)
+
+    * api.get_orders(filters={})
+      -> Get all orders with filters (with pagination)
+
+    * api.get_order(order_id)
+      -> Gets order detail
+
+    * api.get_order_feedbacks(order_id)
+      -> Gets both seller and buyer feedbacks
+
+    * api.get_buyer_feedback(order_id)
+      -> Gets buyer feedback
+
+    * api.get_seller_feedback(order_id)
+      -> Gets seller feedback
+
+    * api.give_feedback_to_order(order_id, feedback_data)
+      -> Gives feedback to order
+
+    * api.change_feedback_from_order(order_id, kind, feedback_data)
+      -> Updates feedback from order. Kind is seller or buyer.
+
+    * api.reply_feedback(order_id, kind, text)
+      -> Reply a feedback. Kind is seller or buyer.
+
+    * api.get_site_payment_methods(site_id)
+      -> Get all payment methods from site.
+
+    * api.get_order_blacklist(user_id)
+      -> Get all users restricted to purchase you an item.
+
+##### Questions
+
+    * api.get_all_questions(filters={})
+      -> Get all questions with filters (without pagination)
+
+    * api.get_questions(filters={})
+      -> Get all questions with filters (with pagination)
+
+    * api.get_question(question_id)
+      -> Gets question detail
+
+    * api.delete_question(question_id)
+      -> Deletes question
+
+    * api.ask_question(item_id, text)
+      -> Asks a question
+
+    * api.answer_question(question_id, text)
+      -> Answers a question
+
+    * api.get_blacklisted_users_ids(seller_id)
+      -> Get all blacklisted users
+
+    * api.add_user_to_blacklist(seller_id, user_id)
+      -> Adds user to blacklist
+
+    * api.remove_user_from_blacklist(seller_id, user_id)
+      -> Removes user from blacklist
+
+##### Users
+
+    * api.get_my_user
+      -> Gets current user
+
+    * api.get_user(user_id)
+      -> Gets user detail
+
+    * api.get_users(user_ids)
+      -> Get all users with user_id from array
+
+    * api.get_user_accepted_payment_methods(user_id)
+      -> Get all accepted payment methods for the user.
+
+**Note:** For further details about the methods, params and possible errors please check https://api.mercadolibre.com.
+
+Problems?
+-----------------
+
+If you are encountering what you think is a bug, please open an issue.
+
+Todo
+-----------------
+
+Error handling should be improved to capture errors for common errors, already quoted on meli API.
+
+
+Author
+-----------------
+
+Matias Hick (me@unformatt.com.ar)

data/lib/mercadolibre.rb

@@ -37,7 +37,7 @@ require "mercadolibre/core/items_and_searches"
 require "mercadolibre/core/locations_and_currencies"
 require "mercadolibre/core/order_management"
 require "mercadolibre/core/questions"
-require "mercadolibre/core/users_and_apps"
+require "mercadolibre/core/users"
 require "mercadolibre/api"
 
 # dependencies

data/lib/mercadolibre/api.rb

@@ -18,7 +18,7 @@ module Mercadolibre
     include Mercadolibre::Core::LocationsAndCurrencies
     include Mercadolibre::Core::OrderManagement
     include Mercadolibre::Core::Questions
-    include Mercadolibre::Core::UsersAndApps
+    include Mercadolibre::Core::Users
 
     private
 

data/lib/mercadolibre/core/items_and_searches.rb

@@ -152,8 +152,8 @@ module Mercadolibre
         put_request("/items/#{item_id}?access_token=#{@access_token}", payload, headers)[:body]
       end
 
-      def update_item_listing_type(item_id, new_listing_kind)
-        payload = { id: new_listing_kind }.to_json
+      def update_item_listing_type(item_id, listing_type_id)
+        payload = { id: listing_type_id }.to_json
 
         headers = { content_type: :json, accept: :json }
 

data/lib/mercadolibre/core/{users_and_apps.rb → users.rb}

@@ -1,6 +1,6 @@
 module Mercadolibre
   module Core
-    module UsersAndApps
+    module Users
       def get_my_user
         result = get_request('/users/me', { access_token: @access_token })
 

data/lib/mercadolibre/version.rb

@@ -1,3 +1,3 @@
 module Mercadolibre
-  VERSION = "0.0.9"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mercadolibre
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.1.0
 platform: ruby
 authors:
 - Matias Hick
@@ -52,7 +52,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.6.7
-description: Connect to meli api
+description: Connect to Mercadolibre through Meli API
 email:
 - unformatt@gmail.com
 executables: []
@@ -70,7 +70,7 @@ files:
 - lib/mercadolibre/core/locations_and_currencies.rb
 - lib/mercadolibre/core/order_management.rb
 - lib/mercadolibre/core/questions.rb
-- lib/mercadolibre/core/users_and_apps.rb
+- lib/mercadolibre/core/users.rb
 - lib/mercadolibre/entity/answer.rb
 - lib/mercadolibre/entity/auth.rb
 - lib/mercadolibre/entity/category.rb
@@ -123,5 +123,5 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: Connect to meli api
+summary: Connect to Mercadolibre through Meli API
 test_files: []