me_api 2.4.0 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eba26dc8650233f06f9e7a6fd2a7f0c39c4efad985fdef065900dba0ed1d520f
-  data.tar.gz: 2f3b45d5a3c8052d8c326fcab320e7fd92d40f87d55903e24c320e608bbecdc2
+  metadata.gz: 60b1301cb0bb6f72cab902ef1b3f435e608013eda2f0044a70bc2b0e02ad0b94
+  data.tar.gz: b1bbec3335f49b905e4dadd983c39a4a6ef45824437037ad3d1395ad452776e4
 SHA512:
-  metadata.gz: 83db71da4de61236728c80a9694949695dd29e98bf114aba171565e51dffb4be51b981754d2562a18fbb0cf8c51d930ca2a66d03909d63b6be33069960c3c760
-  data.tar.gz: 8ea06416c60b8759bb412adc62ff082aa40edae08832fdce9b8f40607f27bf7aa4120abcccd5061195b92603c32ba559672623de118631bc91b999256b58503d
+  metadata.gz: 71dab8161feeb811e8348733c66526f4665d480a5209669d8237e579226114db8cd6685cc8ee115d19fed04f639c1272614c8ba248a48e9ae7d9b55acf108219
+  data.tar.gz: 40e87c3119e723c18fdc35af59f694066df5af5f1533cf39834dc31a84580d1bdcc9872b97f0ee6e6e872406dddb72ea703af44977ed154899a11939f24269f3

data/README.md

@@ -1,58 +1,389 @@
 # MeApi
 
-Wrapper de integração com a API v2 do Melhor Envio para cotação de frete.
+Uma gem Ruby para integração completa com a API do Melhor Envio, permitindo calcular fretes, criar etiquetas, gerenciar envios e muito mais de forma simples e eficiente.
+
+[![Gem Version](https://badge.fury.io/rb/me_api.svg)](https://badge.fury.io/rb/me_api)
 
 [Documentação API Melhor Envio](https://docs.melhorenvio.com.br/reference/introducao-api-melhor-envio)
 
-### Funcionalidades:
-- Autenticação: authorization e refresh_token
-- Cotação de frete
+## Funcionalidades
+
+- ✅ **Autenticação**: Authorization code e refresh token
+- ✅ **Cotação de frete**: Calcular preços de envio
+- ✅ **Gestão de etiquetas**: Criar, pagar, gerar e imprimir etiquetas
+- ✅ **Consultas**: Dados da conta, saldo, pedidos
+- ✅ **Suporte a sandbox**: Ambiente de testes
+- ✅ **Classes auxiliares**: Volume e Product para facilitar o uso
 
 ## Instalação
 
-Adicionar me_api no Gemfile:
+Adicione esta linha ao Gemfile da sua aplicação:
 
 ```ruby
 gem 'me_api'
 ```
-ou
-```shell
-bundle add me_api
-```
 
-Instalar a gem:
+E então execute:
+
+    $ bundle install
+
+Ou instale diretamente com:
+
+    $ gem install me_api
+
+## Configuração
+
+Para usar a gem, você precisa ter credenciais da API do Melhor Envio. Você pode obter essas credenciais criando uma aplicação no painel do desenvolvedor do Melhor Envio.
+
+### Criando um cliente
+
+A gem suporta dois modos de operação:
+- **Produção**: Para uso em ambiente de produção
+- **Sandbox**: Para testes (use `test_mode: true`)
+
+```ruby
+# Cliente de produção
+client = MeApi::Client.new(
+  access_token: "seu_access_token",
+  refresh_token: "seu_refresh_token", 
+  client_id: "seu_client_id",
+  client_secret: "seu_client_secret",
+  token_expires_at: Time.now + 3600
+)
 
-```shell
-bin/rails generate me_api:install
+# Cliente de sandbox/teste
+client = MeApi::Client.new(
+  access_token: "seu_access_token",
+  refresh_token: "seu_refresh_token",
+  client_id: "seu_client_id", 
+  client_secret: "seu_client_secret",
+  token_expires_at: Time.now + 3600,
+  test_mode: true
+)
 ```
 
 ## Uso
 
-### Exemplo
-#### Autorização
+### Formato das respostas
+
+Todas as respostas dos métodos da API retornam objetos `AcObject` ou arrays de `AcObject`. Esses objetos permitem acesso aos dados de duas formas:
+
+- **Notação de ponto**: `response.access_token`
+- **Notação de hash**: `response["access_token"]`
+- **Conversão para JSON**: `response.json` (retorna um hash Ruby)
+
+```ruby
+# Exemplo com refresh_token
+response = client.refresh_token(
+  client_id: "seu_client_id",
+  client_secret: "seu_client_secret",
+  refresh_token: "seu_refresh_token"
+)
+
+# Todas essas formas funcionam:
+puts response.access_token          # "novo_access_token"
+puts response["access_token"]       # "novo_access_token"
+puts response.json["access_token"]  # "novo_access_token"
+
+# Para ver toda a resposta como hash
+puts response.json
+# => {"access_token"=>"...", "refresh_token"=>"...", "expires_in"=>21600, "token_type"=>"Bearer"}
+```
+
+### Autenticação
+
+#### Autorizando uma aplicação
+
+```ruby
+response = client.authorize(
+  client_id: "seu_client_id",
+  client_secret: "seu_client_secret", 
+  code: "codigo_retornado_pela_api",
+  redirect_url: "sua_url_de_redirect"
+)
+
+# Acessando dados da resposta
+puts response.access_token   # "abcde12345"
+puts response.refresh_token  # "asdfghjk123456"
+puts response.expires_in     # 21600
+puts response.token_type     # "Bearer"
+
+# Ou usando notação de hash
+puts response["access_token"]  # "abcde12345"
+puts response["refresh_token"] # "asdfghjk123456"
+```
+
+#### Renovando token
+
+```ruby
+response = client.refresh_token(
+  client_id: "seu_client_id",
+  client_secret: "seu_client_secret",
+  refresh_token: "seu_refresh_token"
+)
+
+# Acessando dados da resposta
+puts response.access_token   # "novo_access_token"
+puts response.refresh_token  # "novo_refresh_token"
+puts response.token_type     # "Bearer"
+```
+
+### Cotação de frete
+
+```ruby
+# Criar objeto de volume/dimensões
+volume = MeApi::Volume.new(
+  width_cm: 20,
+  height_cm: 15, 
+  length_cm: 30,
+  weight_kg: 1.5
+)
+
+# Calcular frete (retorna array de AcObject)
+rates = client.rates(
+  from_postal_code: "13870329",
+  to_postal_code: "88063500", 
+  volume: volume,
+  contents_value_brl: 50.00
+)
+
+# Acessando dados do primeiro resultado
+puts rates.first.price          # Preço do frete mais barato
+puts rates.first.service_name   # Nome do serviço (ex: "PAC")
+puts rates.first.carrier_name   # Nome da transportadora (ex: "Correios")
+
+# Ou usando notação de hash
+puts rates.first["price"]        # Preço do frete
+puts rates.first["service_name"] # Nome do serviço
+```
+
+### Gestão de produtos e volumes
+
+#### Criando produtos
+
+```ruby
+products = [
+  MeApi::Product.new(
+    name: "Produto A",
+    quantity: 2,
+    unitary_value: 25.00
+  ),
+  MeApi::Product.new(
+    name: "Produto B", 
+    quantity: 1,
+    unitary_value: 50.00
+  )
+]
+```
+
+#### Criando volumes
+
+```ruby
+volumes = [
+  MeApi::Volume.new(
+    width_cm: 20,
+    height_cm: 15,
+    length_cm: 30, 
+    weight_kg: 1.5
+  )
+]
+```
+
+### Gestão de etiquetas
+
+#### Adicionando etiqueta ao carrinho
+
+```ruby
+response = client.add_label_to_cart(
+  service_id: 1, # ID do serviço de entrega
+  from_name: "Remetente",
+  from_phone: "(11) 99999-9999",
+  from_email: "remetente@email.com",
+  from_address: "Rua do Remetente",
+  from_address_complement: "Apto 123",
+  from_address_number: "100",
+  from_address_district: "Centro", 
+  from_address_city: "São Paulo",
+  from_postal_code: "01000000",
+  from_address_state_abbr: "SP",
+  from_tax_id: "12345678901", # CPF ou CNPJ
+  to_name: "Destinatário",
+  to_phone: "(11) 88888-8888", 
+  to_email: "destinatario@email.com",
+  to_address: "Rua do Destinatário",
+  to_address_complement: "",
+  to_address_number: "200",
+  to_address_district: "Vila Nova",
+  to_address_city: "Rio de Janeiro", 
+  to_postal_code: "20000000",
+  to_address_state_abbr: "RJ",
+  to_tax_id: "98765432109", # CPF ou CNPJ
+  products: products,
+  volumes: volumes,
+  insurance_value: 100.00
+)
+
+# Acessando dados da resposta
+order_id = response.id          # ID do pedido
+puts response.protocol          # Protocolo do pedido
+puts response["status"]         # Status do pedido
+```
+
+#### Pagando etiqueta
+
+```ruby
+payment_response = client.pay_label(order_id)
+puts payment_response.purchase_id    # ID da compra
+puts payment_response["digitable_line"] # Linha digitável (se boleto)
+```
+
+#### Gerando etiqueta
+
 ```ruby
-api_client = MeApi::Client.new.authorize(client_id: "123456", client_secret: "abcde", code: "a1b2c3d4e5", redirect_url: "https://redirect-url.com")
-# retorna JSON da resposta
-puts api_client["access_token"] # string -> "abcde12345"
-puts api_client["refresh_token"] # string -> "asdfghjk123456"
-puts api_client["expires_in"] # integer -> 216000
+generate_response = client.generate_label(order_id)
+puts generate_response["status"]     # Status da geração
 ```
 
-#### Refresh Token
+#### Imprimindo etiqueta
+
+```ruby
+pdf_response = client.print_label(order_id)
+puts pdf_response.first             # URL do PDF da etiqueta
+```
+
+### Consultas
+
+#### Dados da conta
+
 ```ruby
-api_client = MeApi::Client.new.refresh_token(client_id: "123456", client_secret: "abcde", refresh_token: "asdfghjk123456")
-# retorna JSON da resposta
-puts api_client["access_token"] # string -> "abcde12345"
-puts api_client["refresh_token"] # string -> "qwertyu098765"
-puts api_client["expires_in"] # string -> 21600
+account = client.get_account_data
+puts account.firstname          # Nome do usuário
+puts account.email              # Email da conta
+puts account["document"]        # CPF/CNPJ da conta
+puts account.json               # Todos os dados como hash
 ```
 
-#### Cotação de Frete
+#### Saldo disponível
+
+```ruby
+balance = client.get_balance
+puts balance.current            # Saldo atual
+puts balance["currency"]        # Moeda (BRL)
+```
+
+#### Detalhes de um pedido
+
 ```ruby
-rates = MeApi::Client.new("access_token").rates(from: "01002010", to: "99990971", weight_kg: 10, contents_value_brl: 100.00, height_cm: 15, width_cm: 30, length_cm: 30)
+order = client.get_label(order_id)
+puts order.status               # Status do pedido
+puts order.tracking             # Código de rastreamento
+puts order["service_name"]      # Nome do serviço utilizado
+puts order.json                 # Todos os dados do pedido
+```
+
+## Classes auxiliares
+
+### MeApi::Volume
+
+Representa as dimensões e peso de um pacote:
+
+```ruby
+volume = MeApi::Volume.new(
+  width_cm: 20,    # Largura em centímetros
+  height_cm: 15,   # Altura em centímetros  
+  length_cm: 30,   # Comprimento em centímetros
+  weight_kg: 1.5   # Peso em quilogramas
+)
+
+# Converte para formato da API
+volume.to_api_format
+# => { width: 20, height: 15, length: 30, weight: 1.5 }
+```
+
+### MeApi::Product
+
+Representa um produto a ser enviado:
+
+```ruby
+product = MeApi::Product.new(
+  name: "Nome do produto",     # Nome do produto
+  quantity: 2,                 # Quantidade
+  unitary_value: 25.00        # Valor unitário em reais
+)
+
+# Converte para formato da API
+product.to_api_format
+# => { name: "Nome do produto", quantity: 2, unitary_value: 25.0 }
+```
+
+## Exemplo completo
+
+```ruby
+require 'me_api'
+
+# Configurar cliente
+client = MeApi::Client.new(
+  access_token: "seu_access_token",
+  refresh_token: "seu_refresh_token",
+  client_id: "seu_client_id",
+  client_secret: "seu_client_secret", 
+  token_expires_at: Time.now + 3600
+)
+
+# Calcular frete
+volume = MeApi::Volume.new(width_cm: 20, height_cm: 15, length_cm: 30, weight_kg: 1.5)
+rates = client.rates(
+  from_postal_code: "13870329",
+  to_postal_code: "88063500",
+  volume: volume,
+  contents_value_brl: 50.00
+)
+
+puts "Melhor preço: R$ #{rates.first.price}"
+puts "Serviço: #{rates.first.service_name}"
+
+# Criar pedido
+products = [MeApi::Product.new(name: "Produto A", quantity: 1, unitary_value: 50.00)]
+volumes = [volume]
+
+response = client.add_label_to_cart(
+  service_id: rates.first.id,
+  from_name: "Loja Online",
+  from_phone: "(11) 99999-9999",
+  from_email: "loja@email.com",
+  from_address: "Rua da Loja",
+  from_address_number: "123",
+  from_address_district: "Centro",
+  from_address_city: "São Paulo", 
+  from_postal_code: "13870329",
+  from_address_state_abbr: "SP",
+  from_tax_id: "12345678000123",
+  to_name: "João Silva",
+  to_phone: "(11) 88888-8888",
+  to_email: "joao@email.com", 
+  to_address: "Rua do Cliente",
+  to_address_number: "456",
+  to_address_district: "Vila Nova",
+  to_address_city: "Florianópolis",
+  to_postal_code: "88063500", 
+  to_address_state_abbr: "SC",
+  to_tax_id: "98765432109",
+  products: products,
+  volumes: volumes,
+  insurance_value: 50.00
+)
+
+order_id = response.id    # Usando notação de ponto
+puts "Pedido criado: #{response.protocol}"
+
+# Pagar e gerar etiqueta
+payment = client.pay_label(order_id)
+puts "Pagamento: #{payment.purchase_id}"
 
-#retorna um array de Objetos <MeApi::Client::Rate>
-puts rates[0] # <data MeApi::Client::Rate from="01002010", to="99990971", price=87.3, delivery_range={"min"=>16, "max"=>17}, service_name="PAC", carrier_name="Correios", carrier_logo_url="https://www.melhorenvio.com.br/images/shipping-companies/correios.png">
+generate = client.generate_label(order_id)
+puts "Status geração: #{generate.status}"
 
-puts rates[0].price # 87.3
+# Obter URL do PDF
+pdf_response = client.print_label(order_id)
+puts "Etiqueta: #{pdf_response.first}"
 ```

data/lib/me_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MeApi
-  VERSION = "2.4.0"
+  VERSION = "2.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: me_api
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.4.1
 platform: ruby
 authors:
 - Todas Essas Coisas
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.1.0
 email:
 - contato7bulloleo@gmail.com
 executables: []