cieloz 0.0.7 → 0.0.8

data/README.md

@@ -1,9 +1,261 @@
 [<img src="https://secure.travis-ci.org/fabiolnm/cieloz.png"/>](http://travis-ci.org/fabiolnm/cieloz)
+[<img src="https://codeclimate.com/github/fabiolnm/cieloz.png"/>](https://codeclimate.com/github/fabiolnm/cieloz)
 
 # Cieloz
 
 A utility gem for SpreeCielo Gateway gem.
 
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'cieloz'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install cieloz
+
+# Usage
+
+    This is a quick start guide to Cieloz API. 
+    If you want to learn deeply about Cielo Gateway, read the Getting Started section.
+
+## Low Level API: Requisicao objects
+
+Provides a one-to-one ruby implementation for Cielo specification.
+It's much more verbose than the High Level API, but provide a fine grained relation with Cielo WS API.
+The High Level API is just a wrapper with convenient methods to handle with the Low Level API.
+A developer must instantiates one of the available operations:
+
+ * RequisicaoTransacao
+ * RequisicaoConsulta
+ * RequisicaoCaptura
+ * RequisicaoCancelamento
+
+Then populate them with appropriate data. This gem validates these request objects according to
+Cielo Specifications present at Developer Guide (pages 10, 11, 26, 28 and 30), so it makes error
+handling easier ans faster, before the request is sent to Cielo Web Service.
+
+If the operation is valid, this gem serializes them as XML and submits to Cielo, parsing the
+response as a Transaction (Transacao) or Error (Erro) objects. Both keeps the original XML response
+as a xml attribute, so it can be logged.
+
+### Authorization
+
+    dados_ec  = Cieloz::Configuracao.credenciais
+
+    pedido    = Cieloz::RequisicaoTransacao::DadosPedido.new numero: 123, valor: 5000, moeda: 986,
+                data_hora: now, descricao: "teste", idioma: "PT", soft_descriptor: "13letterstest"
+                
+    pagamento = Cieloz::RequisicaoTransacao::FormaPagamento.new.credito "visa"
+    
+    transacao = Cieloz::RequisicaoTransacao.new dados_ec:         dados_ec,
+                                                dados_pedido:     pedido,
+                                                forma_pagamento:  pagamento,
+                                                url_retorno:      your_callback_url
+                                                
+    response  = transacao.autorizacao_direta.submit
+    
+    response.success? # returned Transacao (with status and id for the created Cielo transaction) or Error object?
+
+### Verify
+
+    consulta = Cieloz::RequisicaoConsulta.new tid: transacao.tid, dados_ec: ec
+    resposta = consulta.submit
+    resposta.autorizada?
+
+### Capture
+
+    captura = Cieloz::RequisicaoCaptura.new tid: transacao.tid, dados_ec: ec
+    resposta = captura.submit
+    resposta.capturada?
+
+### Partial Capture
+
+    value = 1000      # a value less than the authorized
+    captura = Cieloz::RequisicaoCaptura.new tid: transacao.tid, dados_ec: ec, valor: value
+    resposta = captura.submit
+    resposta.capturada?
+
+### Cancel
+
+    cancelar = Cieloz::RequisicaoCancelamento.new tid: transacao.tid, dados_ec: ec
+    resposta = cancelar.submit
+    resposta.cancelada?
+
+### Partial Cancel
+
+    value = 1000      # a value less than the authorized
+    cancelar = Cieloz::RequisicaoCancelamento.new tid: transacao.tid, dados_ec: ec, valor: value
+    resposta = cancelar.submit
+    resposta.cancelada?
+
+## High Level API: Cieloz::Buider
+
+The easiest way to use this gem is through the high level API provided by Cieloz::Builder.
+It provides convenient methods to build the respective Cieloz request objects from your domain model object.
+
+### Cieloz.transacao - builds a RequisicaoTransacao object for Payment Authorization
+    
+    pd = Cieloz.pedido    order 
+    pg = Cieloz.pagamento payment, operacao: :op, parcelas: :installments
+    tx = Cieloz.transacao nil, dados_pedido: pd, forma_pagamento: pg
+
+### Cieloz.consulta - builds RequisicaoConsulta
+
+    consulta = Cieloz.consulta payment
+
+### Cieloz.captura - builds RequisicaoCaptura
+
+    captura = Cieloz.captura payment # total capture
+    
+    or
+    
+    captura = Cieloz.captura payment, value: partial_value
+
+
+### Cieloz.cancelamento - builds RequisicaoCancelamento
+
+    cancelamento = Cieloz.cancelamento payment # total cancel
+    
+    or
+    
+    cancelamento = Cieloz.cancelamento payment, value: partial_cancel
+    
+### Domain Model Mapping Startegies
+
+High Level API uses three different strategies to extract the attribute values required to build Cielo object attribute 
+values to be serialized in XML format and sent to Cielo Web Service (see Domain Model Mapping Strategies below).
+
+When an attribute cannot be resolved from one mapping strategy, Cieloz::Builder retrieves the default values configured
+at Cieloz::Configuracao class:
+
+    @@mode                = :cielo
+    @@moeda               = 986 # ISO 4217 - Manual Cielo, p 11
+    @@idioma              = "PT"
+    @@max_parcelas        = 3
+    @@max_adm_parcelas    = 10
+    @@captura_automatica  = false
+
+#### Default Naming Mappings
+
+When your domain object attribute names are the same as the Cielo Web Service expect.
+
+    order.numero  = "R123456"
+    order.valor   = 12345
+    
+    # creates Cieloz::RequisicaoTransacao::DadosPedido extracting order attributes
+    # that has the same names as DadosPedido attributes
+    pedido = Cieloz.pedido order
+    
+    p pedido.numero
+    $ R123456
+    
+    p pedido.valor
+    $ 12345
+
+#### Domain Model Mappings
+
+When you should provide a mapping between your domain model attributes and Cielo Web Service attributes.
+
+    order.number  = "R123456"
+    order.value   = 12345
+
+    # maps  order.number  to DadosPedido#numero
+    # and   order.value   to DadosPedido#valor
+    pedido = Cieloz.pedido order, numero: :number, valor: :value
+    
+    p pedido.numero
+    $ R123456
+    
+    p pedido.valor
+    $ 12345
+
+#### Explicit Values
+
+When you provide values.
+
+    pedido = Cieloz.pedido nil, numero: "R123456", valor: 12345
+    
+    p pedido.numero
+    $ R123456
+    
+    p pedido.valor
+    $ 12345
+
+#### The strategies can be used together!
+
+    order.descricao = "Hello Cielo!"
+    pedido = Cieloz.pedido source, numero: number, valor: 12345
+    
+    p pedido.numero
+    $ R123456
+    
+    p pedido.valor
+    $ 12345
+
+    p pedido.descricao
+    $ Hello Cielo!
+
+## Configuration
+
+Your application can configure Cieloz::Configuracao default values.
+In a Rails application, it can be done in a config/initializers/cieloz.rb file.
+
+If you don't provide ```credenciais```, all operations will be requested against Cielo Homologation Environment.
+
+When you go to production, you MUST configure ```credenciais``` with your Cielo ```numero``` and ```chave```.
+
+    YourApp::Application.class_eval do
+      # Runs in after initialize block to be able to access url helpers
+      config.after_initialize do
+        # must reload routes to initialize routes.url_helpers
+        reload_routes!
+
+        # These are Global Default Settings, and can be overriden at Bulder / Requisicao method levels
+        Cieloz::Configuracao.tap { |c|
+          # 13 letters descriptor to be printed on the buyer's credit card billing
+          c.soft_descriptor = "Your App name"
+
+          # Callback url: in Cielo Mode this is the location to where Cielo redirects a transaction
+          # after the user types this Credit card data.
+          #
+          # NOTICE: In order to *_url methods to work, it's required to set
+          # in config/application.rb or in one of config/environment initializers:
+          #
+          #   [Rails.application.]routes.default_url_options = { host: "HOSTNAME[:PORT]" }
+          #
+          c.url_retorno     = routes.url_helpers.root_url
+
+          # Credit card data is asked to the user in a page hosted by Cielo. This is the default mode
+          # c.cielo_mode!
+
+          # Your application must provide a view asking credit card data, and provide additional security,
+          # in conformance with PCI Standards: http://www.cielo.com.br/portal/cielo/solucoes-de-tecnologia/o-que-e-ais.html
+          # c.store_mode!
+
+          # default to Cieloz::Homologacao::Credenciais::LOJA if store_mode? and ::CIELO if cielo_mode?
+          # c.credenciais = { numero: "", chave: "" }
+
+          # c.moeda               = 986   # ISO 4217 - Manual Cielo, p 11
+          # c.idioma              = "PT"  # EN and ES available - language to Cielo use in this pages
+
+          # http://www.cielo.com.br/portal/cielo/produtos/cielo/parcelado-loja.html
+          # c.max_parcelas        = 3     # no additional interest rates
+
+          # http://www.cielo.com.br/portal/cielo/produtos/cielo/parcelado-administradora.html
+          # c.max_adm_parcelas    = 10    # available with Cielo interest rate
+
+          # if true, payments are automatically captured by authorization request
+          # c.captura_automatica  = false
+        }
+      end
+    end
+
 ## Getting Started
 
 This is a step-by-step guide to enable Cielo Gateway as a payment method to your e-commerce store.
@@ -108,6 +360,8 @@ if supported by the selected credit card (Verified by Visa or MasterCard Secure
 After authentication/authorization flow, if the user has available credit, the
 transaction assumes Status 4 - AUTHORIZED (Autorizada).
 
+#### RequisicaoCaptura
+
 When the transaction is at AUTHORIZED state, the Store Owner must capture this payment in the
 next five days. This can be done with a CaptureRequest (RequisicaoCaptura)
 
@@ -116,6 +370,8 @@ After capture, the transaction assumes Status 6 - CAPTURED (Capturada).
 
 * Manual Capture can be useful for fraud prevention, but it requires aditional Admin efforts.
 
+#### RequisicaoCancelamento
+
 In the 90 days that follows the Authorization or Capture, the transaction can be fully or
 partially cancelled, assuming state 9 - CANCELLED (Cancelada). This can be done with a
 CancelRequest (RequisicaoCancelamento).
@@ -123,44 +379,11 @@ CancelRequest (RequisicaoCancelamento).
 * At any time, a pending request can be expired at Cielo Gateway, that puts the transaction in CANCELLED state.
 * Each state has its own expire time, see the Developer Guide for detailed information.
 
+#### RequisicaoConsulta
+
 At any time, a QueryRequest (RequisicaoConsulta) can be made for a specific transaction
 (identified by its TID) to query about the state of the transaction.
 
-### What is this gem about?
-
-This gem provides a Ruby integration solution that consumes Cielo Web Services.
-
-A developer just instantiates one of the available operations:
-
- * RequisicaoTransacao
- * RequisicaoConsulta
- * RequisicaoCaptura
- * RequisicaoCancelamento
-
-Then populates them with appropriate data. This gem validates these request objects according to
-Cielo Specifications present at Developer Guide (pages 10, 11, 26, 28 and 30), so it makes error
-handling easier, before the request is sent to Cielo Web Service.
-
-If the operation is valid, this gem serializes them as XML and submits to Cielo, parsing the
-response as a Transaction (Transacao) or Error (Erro) objects. Both keeps the original XML response
-as a xml attribute, so it can be logged.
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'cieloz'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install cieloz
-
-## Usage
-
 ## Contributing
 
 1. Fork it

data/lib/cieloz/requisicao_transacao/dados_portador.rb

@@ -26,7 +26,7 @@ class Cieloz::RequisicaoTransacao
 
     def initialize attrs={}
       super
-      indicador_nao_informado!
+      indicador_nao_informado! if codigo_seguranca.blank?
     end
 
     def codigo_seguranca= codigo

data/lib/cieloz/version.rb

@@ -1,3 +1,3 @@
 module Cieloz
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
 end

data/test/unit/validations_test.rb

@@ -8,6 +8,12 @@ describe Cieloz::Requisicao::DadosEc do
 end
 
 describe Cieloz::RequisicaoTransacao::DadosPortador do
+  let(:_) { subject.class }
+
+  it "must not override codigo_seguranca if it's given for initializer" do
+    _.new(codigo_seguranca: "123").codigo_seguranca.wont_be_nil
+  end
+
   it { must ensure_length_of(:nome_portador).is_at_most(50) }
 
   it { must validate_presence_of :numero }
@@ -36,7 +42,6 @@ describe Cieloz::RequisicaoTransacao::DadosPortador do
   end
 
   describe "indicador and codigo_seguranca validation" do
-    let(:_) { subject.class }
     let(:code) { 123 }
 
     before do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cieloz
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-24 00:00:00.000000000 Z
+date: 2013-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri