moip2 0.1.4 → 1.0.0

data/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+:clap::tada: Thank you for taking the time to contribute! :tada::clap:
+
+We really value your willingness to contribute to this project. In order to higher the chances of your contribution being accepted, please refer to the following guidelines!
+
+## Steps
+
+1. Fork it!
+2. Create your feature branch: `git checkout -b feature/xyz develop`
+3. Commit your changes according to our commit message standards: `git commit -am 'feat(xyz) Added new functionality'`
+4. Push to your repo: `git push origin feature/xyz`
+5. Submit a pull request to `develop`
+
+## Workflow
+This repo uses Gitflow as its branch management system. You can learn more about Gitflow [here](https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow).
+A few quick tips:
+* All feature branches should be based on `develop` and have the format `feature/branch_name`. 
+* Minor bug fixes should be based on `master` and have the format `hotfix/branch_name`.
+
+### Commit Conventions
+In order to make the changelog generation easier we recommend the use of messages based on [Conventional Commits](https://conventionalcommits.org/).
+
+Examples:
+```
+feat(orders): added `XYZ` helper function
+
+commit description
+
+footer notes
+```
+
+```
+refactor(orders): refactored `ABC` helper function
+
+The behaviour of `ABC` was inconsistent and (...)
+
+BREAKING CHANGE: return type of `ABC` is now `String`
+```
+
+```
+docs: updated documentation in Request.php
+```

data/Gemfile

@@ -1,4 +1,4 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in moip2.gemspec
 gemspec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    moip2 (0.1.3)
+    moip2 (0.1.5)
       httparty
       recursive-open-struct
 
@@ -9,6 +9,7 @@ GEM
   remote: https://rubygems.org/
   specs:
     addressable (2.3.8)
+    ast (2.3.0)
     celluloid (0.16.0)
       timers (~> 4.0.0)
     codeclimate-test-reporter (0.4.7)
@@ -35,8 +36,7 @@ GEM
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
     hitimes (1.2.2)
-    httparty (0.13.7)
-      json (~> 1.8)
+    httparty (0.14.0)
       multi_xml (>= 0.5.2)
     json (1.8.3)
     listen (2.10.0)
@@ -45,20 +45,26 @@ GEM
       rb-inotify (>= 0.9)
     lumberjack (1.0.9)
     method_source (0.8.2)
-    multi_xml (0.5.5)
+    multi_xml (0.6.0)
     nenv (0.2.0)
     notiffany (0.0.6)
       nenv (~> 0.1)
       shellany (~> 0.0)
+    parallel (1.11.2)
+    parser (2.4.0.0)
+      ast (~> 2.2)
+    powerpack (0.1.1)
     pry (0.10.1)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
       slop (~> 3.4)
+    rainbow (2.2.2)
+      rake
     rake (10.4.2)
     rb-fsevent (0.9.5)
     rb-inotify (0.9.5)
       ffi (>= 0.5.0)
-    recursive-open-struct (0.6.5)
+    recursive-open-struct (1.0.2)
     rspec (3.3.0)
       rspec-core (~> 3.3.0)
       rspec-expectations (~> 3.3.0)
@@ -72,6 +78,14 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.3.0)
     rspec-support (3.3.0)
+    rubocop (0.49.1)
+      parallel (~> 1.10)
+      parser (>= 2.3.3.1, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.8.1)
     safe_yaml (1.0.4)
     shellany (0.0.1)
     simplecov (0.10.0)
@@ -83,6 +97,7 @@ GEM
     thor (0.19.1)
     timers (4.0.1)
       hitimes
+    unicode-display_width (1.3.0)
     vcr (2.9.3)
     webmock (1.21.0)
       addressable (>= 2.3.6)
@@ -92,11 +107,15 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.5)
+  bundler
   codeclimate-test-reporter
   guard-rspec
   moip2!
   rake
   rspec
+  rubocop (= 0.49.1)
   vcr
   webmock
+
+BUNDLED WITH
+   1.15.1

data/Guardfile

@@ -4,6 +4,5 @@
 guard :rspec do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')  { "spec" }
+  watch("spec/spec_helper.rb")  { "spec" }
 end
-

data/README.md

@@ -1,10 +1,70 @@
+<img src="https://gist.githubusercontent.com/joaolucasl/00f53024cecf16410d5c3212aae92c17/raw/1789a2131ee389aeb44e3a9d5333f59cfeebc089/moip-icon.png" align="right" />
+
 # Moip v2 Ruby SDK
+> O jeito mais simples e rápido de integrar o Moip a sua aplicação Ruby
 
 [![Build Status](https://travis-ci.org/moip/moip-sdk-ruby.svg?branch=master)](https://travis-ci.org/moip/moip-sdk-ruby)
 [![Code Climate](https://codeclimate.com/github/moip/moip-sdk-ruby/badges/gpa.svg)](https://codeclimate.com/github/moip/moip-sdk-ruby)
 [![Test Coverage](https://codeclimate.com/github/moip/moip-sdk-ruby/badges/coverage.svg)](https://codeclimate.com/github/moip/moip-sdk-ruby/coverage)
 
-O jeito mais simples e rápido de integrar o Moip a sua aplicação Ruby
+**Índice** 
+
+- [Instalação](#instalação)
+- [Configurando a autenticação](#configurando-a-autenticação)
+  - [Por BasicAuth](#por-basicauth)
+  - [Por OAuth](#por-oauth)
+- [Configurando o ambiente](#configurando-o-ambiente)
+- [Exemplos de Uso](#clientes):
+  - [Clientes](#clientes)
+    - [Criação](#criação)
+    - [Consulta](#consulta)
+    - [Adicionar cartão de crédito](#adicionar-cartão-de-crédito)
+    - [Deletar cartão de crédito](#deletar-cartão-de-crédito)
+  - [Pedidos](#pedidos)
+    - [Criação](#criação-1)
+    - [Consulta](#consulta-1)
+      - [Pedido Específico](#pedido-específico)
+      - [Todos os Pedidos](#todos-os-pedidos)
+        - [Sem Filtro](#sem-filtro)
+        - [Com Filtros](#com-filtros)
+        - [Com Paginação](#com-paginação)
+  - [Pagamentos](#pagamentos)
+    - [Criação](#criação-2)
+      - [Cartão de Crédito](#cartão-de-crédito)
+        - [Com Hash](#com-hash)
+        - [Com Dados do Cartão](#com-dados-do-cartão)
+      - [Com Boleto](#com-boleto)
+    - [Consulta](#consulta-2)
+    - [Capturar pagamento pré-autorizado](#capturar-pagamento-pré-autorizado)
+    - [Cancelar pagamento pré-autorizado](#cancelar-pagamento-pré-autorizado)
+  - [Reembolsos](#reembolsos)
+    - [Criação](#criação-3)
+      - [Valor Total](#valor-total)
+      - [Valor Parcial](#valor-parcial)
+    - [Consulta](#consulta-3)
+  - [Multipedidos](#multipedidos)
+    - [Criação](#criação-4)
+    - [Consulta](#consulta-4)
+  - [Multipagamentos](#multipagamentos)
+    - [Criação](#criação-5)
+    - [Consulta](#consulta-5)
+  - [Conta Moip](#conta-moip)
+    - [Criação](#criação-6)
+    - [Consulta](#consulta-6)
+    - [Verifica se usuário já possui Conta Moip](#verifica-se-usuário-já-possui-conta-moip)
+  - [OAuth (Moip Connect)](#oauth-(moip-connect))
+    - [Solicitar permissões de acesso ao usuário](#solicitar-permissões-de-acesso-ao-usuário)
+    - [Gerar Token OAuth](#gerar-token-oauth)
+    - [Atualizar Token OAuth](#atualizar-token-oauth)
+  - [Preferências de Notificação](#preferências-de-notificação)
+    -  [Criação](#criação-7)
+    -  [Consulta](#consulta-7)
+    -  [Exclusão](#exclusão)
+    -  [Listagem](#listagem)
+- [Tratamento de Exceções](#tratamento-de-exceções)
+- [Documentação](#documentação)
+- [Licença](#licença)
+
 
 ## Instalação
 
@@ -14,91 +74,145 @@ Adicione a seguinte linha no seu Gemfile:
 gem "moip2"
 ```
 
-## Configurando sua autenticação
-- Autenticando por BasicAuth
+## Configurando a autenticação
+### Por BasicAuth
 ```ruby
 auth = Moip2::Auth::Basic.new("TOKEN", "SECRET")
 ```
-- Autenticando por OAuth
+### Por OAuth
 ```ruby
 auth = Moip2::Auth::OAuth.new("TOKEN_OAUTH")
 ```
 
-Após deifinir o tipo de autenticação, é necessário gerar o client, informando em qual environment você quer executar suas ações:
+## Configurando o ambiente
+Após definir o tipo de autenticação, é necessário gerar o client, informando em qual ambiente você quer executar suas ações:
 ```ruby
 client = Moip2::Client.new(:sandbox/:production, auth)
 ```
 
-Agora você pode instanciar a Api:
+Após isso, é necessário instanciar um ponto de acesso a partir do qual você utilizará as funções da API:
+
 ```ruby
 api = Moip2::Api.new(client)
 ```
 
-## Criando um Pedido
+## Clientes
+### Criação
+```ruby
+customer = api.customer.create({
+  ownId: "meu_id_de_cliente",
+  fullname: "Jose Silva",
+  email: "josedasilva@email.com",
+  phone: {
+    #...
+  },
+  birthDate: "1988-12-30",
+  taxDocument: {
+    #...
+  },
+  shippingAddress: {
+    #...
+  },
+  fundingInstrument: {
+    # Campo opcional. Consulte a documentação da API.
+  }
+})
+```
+### Consulta
+```ruby
+customer = api.customer.show("CUS-V41BR451L")
+```
 
+### Adicionar cartão de crédito
 ```ruby
-order = api.order.create(
+credit_card = api.customer.add_credit_card("CUSTOMER-ID", 
     {
-        own_id: "ruby_sdk_1",
-        items: [
-          {
-            product: "Nome do produto",
-            quantity: 1,
-            detail: "Mais info...",
-            price: 1000
-          }
-        ],
-        customer: {
-          own_id: "ruby_sdk_customer_1",
-          fullname: "Jose da Silva",
-          email: "sandbox_v2_1401147277@email.com",
-        }
+      method: "CREDIT_CARD",
+      creditCard: {
+        expirationMonth: "05",
+        expirationYear: "22",
+        number: "5555666677778884",
+        cvc: "123",
+        holder: {
+          fullname: "Jose Portador da Silva",
+          birthdate: "1988-12-30",
+          taxDocument: {
+            type: "CPF",
+            number: "33333333333",
+          },
+          phone: {
+            countryCode: "55",
+            areaCode: "11",
+            number: "66778899",
+          },
+        },
+      },
     }
 )
 ```
 
-### Pedido com dados completos do Comprador
+### Deletar cartão de crédito
+
+> Retorna uma Exception do tipo `NotFoundError` caso não encontre o cartão de crédito para deletar
+
+```ruby
+api.customer.delete_credit_card!("CREDIT-CARD-ID")
+```
+
+> Retorna `false` caso não encontre o cartão de crédito para deletar
+
+```ruby
+api.customer.delete_credit_card("CREDIT-CARD-ID")
+```
 
-Agora basta criar o pedido:
+## Pedidos
+### Criação
 
 ```ruby
-order = api.order.create(
+order = api.order.create({
+  own_id: "ruby_sdk_1",
+  items: [
     {
-        own_id: "ruby_sdk_1",
-        items: [
-          {
-            product: "Nome do produto",
-            quantity: 1,
-            detail: "Mais info...",
-            price: 1000
-          }
-        ],
-        customer: {
-          own_id: "ruby_sdk_customer_1",
-          fullname: "Jose da Silva",
-          email: "sandbox_v2_1401147277@email.com",
-          birthdate: "1988-12-30",
-          tax_document: { number: "33333333333", type: "CPF" },
-          phone: { country_code: "55", area_code: "11", number: "66778899" },
-          shipping_address: 
-            {
-              street: "Avenida Faria Lima",
-              street_number: 2927,
-              complement: 8,
-              district: "Itaim",
-              city: "Sao Paulo",
-              state: "SP",
-              country: "BRA",
-              zip_code: "01234000"
-            }
-        }
+      product: "Nome do produto",
+      quantity: 1,
+      detail: "Mais info...",
+      price: 1000
     }
-)
+  ],
+  customer: {
+    own_id: "ruby_sdk_customer_1",
+    fullname: "Jose da Silva",
+    email: "sandbox_v2_1401147277@email.com",
+  }
+})
+```
+### Consulta
+#### Pedido Específico
+```ruby
+order = api.order.show("ORD-V41BR451L")
+```
+
+#### Todos os Pedidos
+##### Sem Filtro
+```ruby
+orders = api.order.find_all()
+```
+
+##### Com Filtros
+```ruby
+orders = api.order.find_all(filters: { status: { in: ["PAID", "WAITING"] }, amount: { bt: [500, 1000] } })
 ```
 
-## Criando um pagamento
+##### Com Paginação
+```ruby
+orders = api.order.find_all(limit: 10, offset: 50)
+```
 
-### Cartão de crédito com hash
+## Pagamentos
+
+### Criação
+#### Cartão de Crédito 
+##### Com Hash
 
 ```ruby
 api.payment.create(order.id,
@@ -107,7 +221,7 @@ api.payment.create(order.id,
         funding_instrument: {
             method: "CREDIT_CARD",
             credit_card: {
-                hash: "valor do cartã criptografado vindo do JS",
+                hash: "valor do cartão criptografado vindo do JS",
                 holder: {
                     fullname: "Jose Portador da Silva",
                     birthdate: "1988-10-10",
@@ -122,7 +236,8 @@ api.payment.create(order.id,
 )
 ```
 
-### Cartão de crédito
+##### Com Dados do Cartão 
+> Esses método requer certificação PCI. [Consulte a documentação.](https://documentao-moip.readme.io/v2.0/reference#criar-pagamento)
 
 ```ruby
 api.payment.create(order.id,
@@ -133,20 +248,10 @@ api.payment.create(order.id,
             credit_card: {
                 expiration_month: 04,
                 expiration_year: 18,
-                number: "4012001038443335",
+                number: "4002892240028922",
                 cvc: "123",
                 holder: {
-                    fullname: "Jose Portador da Silva",
-                    birthdate: "1988-10-10",
-                    tax_document: {
-                        type: "CPF",
-                        number: "22222222222"
-                },
-                    phone: {
-                        country_code: "55",
-                        area_code: "11",
-                        number: "55667788"
-                    }
+                    # ...
                 }
             }
         }
@@ -154,26 +259,220 @@ api.payment.create(order.id,
 )
 ```
 
-### Boleto
+#### Com Boleto
 
 ```ruby
-api.payment.create(
+api.payment.create(order.id,
     {
+      # ...
         funding_instrument: {
             method: "BOLETO",
             boleto: {
-                expiration_date: "2015-09-30",
+                expiration_date: "2017-09-30",
                 instruction_lines: {
                     first: "Primeira linha do boleto",
                     second: "Segunda linha do boleto",
                     third: "Terceira linha do boleto"
                   },
-                logo_uri: "https://"
+                logo_uri: "https://sualoja.com.br/logo.jpg"
             }
         }
     }
 )
 ```
+
+### Consulta
+```ruby
+pagamento = api.payment.show("PAY-CRUP19YU2VE1")
+```
+
+### Capturar pagamento pré-autorizado
+```ruby
+api.payment.capture("PAY-KT5OSI01X8QU")
+```
+
+### Cancelar pagamento pré-autorizado
+```ruby
+api.payment.void("PAY-IXNGCU456GG4")
+```
+
+## Reembolsos
+### Criação
+#### Valor Total
+```ruby
+reembolso = api.refund.create("ORD-V41BR451L")
+```
+#### Valor Parcial
+```ruby
+reembolso = api.refund.create("ORD-V41BR451L", amount: 2000)
+```
+
+### Consulta
+```ruby
+reembolso = api.refund.show("REF-V41BR451L")
+```
+
+## Multipedidos
+### Criação
+```ruby
+multi = api.multi_order.create(
+  {
+    ownId: "meu_multiorder_id",
+    orders: [
+      {
+        # Objeto Order 1
+      },
+      {
+        # Objeto Order 2
+      }
+    ]
+  }
+)
+```
+### Consulta
+```ruby
+multi = api.multi_order.show("MOR-V41BR451L")
+```
+### Nota
+> 1. Essa função depende de permissões das contas associadas ao recebimento.  [Consulte a documentação.](https://documentao-moip.readme.io/v2.0/reference#multipedidos)
+> 2. Para reembolsos de multipedidos, é necessario reembolsar os pedidos individualmente. [Consulte a documentação.](https://documentao-moip.readme.io/v2.0/reference#multipedidos)
+
+## Multipagamentos
+### Criação
+```ruby
+multi_pag = api.multi_payment.create("MOR-V41BR451L",
+  {
+    installmentCount: 1,
+    fundingInstrument: {
+      # ... 
+    }
+  }
+)
+```
+### Consulta
+```ruby
+multi_pag = api.multi_payment.show("MPY-V41BR451L")
+```
+
+## Conta Moip
+### Criação
+```ruby
+account = api.accounts.create(
+  {
+    email: {
+      address: "dev.moip@labs.moip.com.br",
+    },
+    person: {
+      name: "Joaquim José",
+      lastName: "Silva Silva",
+      taxDocument: {
+        type: "CPF",
+        number: "572.619.050-54",
+      },
+      identityDocument: {
+        type: "RG",
+        number: "35.868.057-8",
+        issuer: "SSP",
+        issueDate: "2000-12-12",
+      },
+      birthDate: "1990-01-01",
+      phone: {
+        countryCode: "55",
+        areaCode: "11",
+        number: "965213244",
+      },
+      address: {
+        street: "Av. Brigadeiro Faria Lima",
+        streetNumber: "2927",
+        district: "Itaim",
+        zipCode: "01234-000",
+        city: "S\u00E3o Paulo",
+        state: "SP",
+        country: "BRA",
+      },
+    },
+    type: "MERCHANT"
+  }
+)
+```
+
+### Consulta
+```ruby
+account = api.accounts.show("MPA-12312312312")
+```
+
+### Verifica se usuário já possui Conta Moip
+```ruby
+api.accounts.exists?("123.456.789.10")
+```
+
+## OAuth (Moip Connect)
+### Solicitar permissões de acesso ao usuário
+```ruby
+api.connect.authorize_url("APP-ID","http://localhost/moip/callback","RECEIVE_FUNDS,REFUND")
+```
+
+### Gerar token OAuth
+```ruby
+api.connect.authorize(
+  client_id: "APP-YRYCCJ5P603B",
+  client_secret: "363cdf8ab70a4c5aa08017564c08efbe",
+  code: "4efde1f89d9acc3b12124ccfded146518465e423",
+  redirect_uri: "http://localhost/moip/callback",
+  grant_type: "authorization_code"
+)
+```
+
+### Atualizar token OAuth
+```ruby
+api.connect.authorize(
+  refresh_token: "1d5dc51e71674683b4ed79cd7a988fa1_v2",
+  grant_type: "refresh_token"
+)
+```
+
+## Preferências de notificação
+
+### Criação
+```ruby
+api.notifications.create(
+  events: ["ORDER.*", "PAYMENT.AUTHORIZED", "PAYMENT.CANCELLED"],
+  target: "http://requestb.in/1dhjesw1",
+  media: "WEBHOOK"
+)
+```
+
+### Consulta
+```ruby
+api.notifications.show("NOTIFICATION-ID")
+```
+
+### Exclusão
+> Caso o notification não seja encontrado uma exceção do tipo `NotFoundError` será lançada, veja como tratar [aqui](#tratamento-de-exceções).
+
+```ruby
+api.notifications.delete("NOTIFICATION-ID")
+```
+
+### Listagem
+```ruby
+api.notifications.find_all
+```
+
+## Tratamento de Exceções
+
+Caso algum recurso não seja encontrado uma exceção do tipo `NotFoundError` será lançada.
+
+```ruby
+begin
+  api.payment.create(
+    # ...
+  )
+rescue NotFoundError => e
+  puts e.message
+end
+```
+
 ## Documentação
 
 [Documentação oficial](https://moip.com.br/referencia-api/)

data/Rakefile

@@ -1,11 +1,11 @@
 require "bundler/gem_tasks"
 
 begin
-  require 'rspec/core/rake_task'
+  require "rspec/core/rake_task"
 
   RSpec::Core::RakeTask.new(:spec)
 
-  task :default => :spec
+  task default: :spec
 rescue LoadError
   # no rspec available
 end