mercado_livre_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4c78b8b5d387198744fca75d8c77d372bde101b2c1a5d6117ee3b7d56e3d4cc
+  data.tar.gz: 74a9a1fe28494f6525ff0210b2dc0cde0682e97fe9f85c1fe0b3f7e9afa6545a
+SHA512:
+  metadata.gz: 31cd6e0091c48a92d84e75b15692167d4893f7ef29de0fd6370a6b572c383b687b7477f05affbe59dca10e80936acb15c4000dcb098b8d221c3e790924a1b630
+  data.tar.gz: e1dc377c3fac7093308805d22a511de11fc1c05cb43847bb3097a700e3516e30bd734e74275579b35ce8ec4afc4e5138417241463e1a6bfa543adbaa0b280abb

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-08-17
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"mercado_livre_api" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["marialuiza.nerypinto@yahoo.com.br"](mailto:"marialuiza.nerypinto@yahoo.com.br").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 marialuiza1324
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+# MercadoLivreApi
+
+Cliente Ruby para a API do Mercado Livre: autenticação OAuth (geração de
+código, troca por token, refresh) e endpoints de pedidos, itens, informações
+de faturamento, envios (incluindo etiqueta), nota fiscal e packs. Construído
+em cima da gem [`ac`](https://rubygems.org/gems/ac) (`Ac::Base`), que cuida
+das requisições HTTP, parsing da resposta e do fluxo de autenticação.
+
+Usado pelo [`solidus_mercado_livre`](https://github.com/todasessascoisas/solidus_mercado_livre)
+para integrar o Mercado Livre como canal de marketplace no Solidus, mas não
+depende de Rails/Solidus — pode ser usado isoladamente.
+
+## Requisitos
+
+- Ruby >= 3.2.0
+- `ac`
+
+## Instalação
+
+Adicione ao `Gemfile` da aplicação:
+
+```ruby
+gem "mercado_livre_api"
+```
+
+E então execute:
+
+```bash
+bundle install
+```
+
+Ou instale diretamente:
+
+```bash
+gem install mercado_livre_api
+```
+
+## Uso
+
+### Autenticação (OAuth)
+
+```ruby
+client = MercadoLivreApi::Client.new(
+  client_id: "...",
+  client_secret: "...",
+  redirect_uri: "https://seuapp.com/mercado_livre/authorize"
+)
+
+# 1. Redirecione o usuário para client.generate_code
+# 2. Depois do callback, troque o `code` recebido pelo token:
+client.authorize(params[:code])
+client.access_token   # => token de acesso
+client.user_id        # => id do vendedor autenticado
+
+# Persista o necessário pra reconstruir o client depois:
+client.token_attributes # => { access_token:, refresh_token:, token_expires_at: }
+```
+
+Para reconstruir um client já autenticado a partir de tokens salvos:
+
+```ruby
+client = MercadoLivreApi::Client.new(
+  client_id: "...",
+  client_secret: "...",
+  redirect_uri: "...",
+  access_token: saved_access_token,
+  refresh_token: saved_refresh_token,
+  token_expires_at: saved_token_expires_at
+)
+
+client.refresh_token if client.should_refresh?
+```
+
+### Pedidos e envios
+
+```ruby
+client.get_order(order_id)
+client.get_orders(user_id: seller_id, from: 1.day.ago, to: Time.current) # pagina automaticamente
+client.get_items(order_id)
+client.get_billing_info(billing_info_id)
+
+client.get_shipment(shipment_id)
+client.get_shipment_label(shipment_id)
+client.get_shipment_costs(shipment_id)
+
+client.get_pack(pack_id)
+```
+
+### Nota fiscal
+
+```ruby
+client.send_invoice_xml(shipment_id, xml)     # importa a NF-e, libera a etiqueta
+client.update_invoice_xml(invoice_id, xml)    # atualiza uma NF-e já enviada
+client.get_invoice_data(shipment_id)
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/todasessascoisas/mercado_livre_api.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/lib/mercado_livre_api/client.rb

@@ -0,0 +1,149 @@
+module MercadoLivreApi
+  class Client < Ac::Base
+    BASE_URL = "https://api.mercadolibre.com"
+    SAVE_RESPONSES = true
+
+    attr_reader :user_id, :client_id, :client_secret, :redirect_uri
+
+    def initialize(client_id:, client_secret:, redirect_uri:, access_token: nil, refresh_token: nil, token_expires_at: nil)
+      @client_id = client_id
+      @client_secret = client_secret
+      @redirect_uri = redirect_uri
+      @access_token = access_token
+      @refresh_token = refresh_token
+      @token_expires_at = token_expires_at
+    end
+
+    def generate_code
+      body = URI.encode_www_form(
+        response_type: "code",
+        client_id: client_id,
+        redirect_uri: redirect_uri
+      )
+      "https://auth.mercadolivre.com.br/authorization?" + body
+    end
+
+    def authorize(code)
+      body = {
+        grant_type: "authorization_code",
+        client_id: client_id,
+        client_secret: client_secret,
+        code: code,
+        redirect_uri: redirect_uri
+      }
+      response = post("/oauth/token", body:, skip_authentication: true) { _1["access_token"] }
+      @access_token = response.access_token
+      @refresh_token = response.refresh_token
+      @token_expires_at = Time.now + response.expires_in.to_i
+      @user_id = response.user_id
+    end
+
+    def refresh_token
+      body = {
+        grant_type: "refresh_token",
+        client_id: client_id,
+        client_secret: client_secret,
+        refresh_token: @refresh_token
+      }
+      response = post("/oauth/token", body:, skip_authentication: true) { _1["access_token"] }
+      @access_token = response.access_token
+      @refresh_token = response.refresh_token
+      @token_expires_at = Time.now + response.expires_in.to_i
+    end
+
+    def get_refresh_token
+      @refresh_token
+    end
+
+    def should_refresh?
+      @access_token.blank? || (@token_expires_at && @token_expires_at < 1.hour.from_now)
+    end
+
+    def token_attributes
+      {
+        access_token: access_token,
+        refresh_token: @refresh_token,
+        token_expires_at: token_expires_at
+      }
+    end
+
+    def fetch_resource(path)
+      get(path)
+    end
+
+    def get_order(order_id)
+      get("/orders/#{order_id}") { _1.id }
+    end
+
+    def get_orders(user_id:, from: nil, to: nil, offset: 0)
+      params = {
+        seller: user_id,
+        sort: "date_asc"
+      }
+      params["order.date_created.from"] = from.iso8601 if from
+      params["order.date_created.to"] = to.iso8601 if to
+
+      results = []
+      total = nil
+
+      while total.nil? || offset < total
+        params.merge!(offset:)
+        page = get("/orders/search", params:) { _1.results.is_a?(Array) }.json
+        page_results = page.fetch("results", [])
+        break if page_results.empty?
+
+        results.concat(page_results)
+        offset += page_results.size
+        total = page.dig("paging", "total") || offset
+      end
+
+      results
+    end
+
+    def get_items(order_id)
+      get("/orders/#{order_id}/items")
+    end
+
+    def get_billing_info(billing_info_id)
+      get("/orders/billing-info/MLB/#{billing_info_id}")
+    end
+
+    def get_shipment(shipment_id)
+      get("/shipments/#{shipment_id}")
+    end
+
+    def get_shipment_label(shipment_id)
+      params = {
+        shipment_ids: shipment_id,
+        response_type: "pdf"
+      }
+      get("/shipment_labels", params:)
+    end
+
+    # importação de NF-e — desbloqueia o substatus invoice_pending do envio e libera a geração da etiqueta
+    def send_invoice_xml(shipment_id, xml)
+      headers = {"Content-Type" => "application/xml"}
+      params = {siteId: "MLB"}
+      post("/shipments/#{shipment_id}/invoice_data/", headers:, params:, body: xml)
+    end
+
+    def update_invoice_xml(invoice_id, xml)
+      headers = {"Content-Type" => "application/xml"}
+      params = {siteId: "MLB"}
+      put("/shipment_invoice/#{invoice_id}", headers:, params:, body: xml)
+    end
+
+    def get_invoice_data(shipment_id)
+      params = {siteId: "MLB"} 
+      get("/shipments/#{shipment_id}/invoice_data", params:)
+    end
+
+    def get_shipment_costs(shipment_id)
+      get("/shipments/#{shipment_id}/costs")
+    end
+
+    def get_pack(pack_id)
+      get("/packs/#{pack_id}") { _1.id }
+    end
+  end
+end

data/lib/mercado_livre_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MercadoLivreApi
+  VERSION = "0.1.0"
+end

data/lib/mercado_livre_api.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+require "ac"
+
+require_relative "mercado_livre_api/version"
+require_relative "mercado_livre_api/client"
+
+module MercadoLivreApi
+  class Error < StandardError; end
+end

data/sig/mercado_livre_api.rbs

@@ -0,0 +1,4 @@
+module MercadoLivreApi
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: mercado_livre_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- marialuiza1324
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ac
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- marialuiza.nerypinto@yahoo.com.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/mercado_livre_api.rb
+- lib/mercado_livre_api/client.rb
+- lib/mercado_livre_api/version.rb
+- sig/mercado_livre_api.rbs
+homepage: https://github.com/todasessascoisas/mercado_livre_api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/todasessascoisas/mercado_livre_api
+  source_code_uri: https://github.com/todasessascoisas/mercado_livre_api
+  changelog_uri: https://github.com/todasessascoisas/mercado_livre_api
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Ruby client for the Mercado Livre — OAuth authentication and endpoints for
+  orders, shipments, shipping labels and invoices.
+test_files: []