fellix / cielorb

Gem para comunicação com os serviços da cielo

Cielorb

Gem para comunicação com os serviços da cielo de processamento de pagamento.

Esse projeto se encontra em desenvolvimento nesse momento.

Instalação

Adicione essa linha ao Gemfile da sua aplicação:

gem 'cielorb', :git => "git://github.com/fellix/cielorb.git"

Então execute:

$ bundle

Usage

Primeiro você deve definir a especificação de conexão, que pode ser uma instancia de Cielo::Spec, ou um objeto que responda a mesma assinatura

spec = Cielo::Spec.new(token: "MyToken", number: "MyNumber", endpoint: "URL do serviço a ser enviado os dados")

Com a spec definida, é possível acessar os serviços da cielo.

Criando transações

Uma transação é uma operação para efeturar uma cobrança em um determinado cartão

transaction = Cielo::Transaction.new(spec) do |request|
  request.payer_data do |data|
    data.number "4242 4242 4242 4242"
  end
end

transaction.create
# => true

transaction.success?
# => true

transaction.failure?
# => false

transaction.create # criando segunda vez consecutiva
# => Cielo::Transaction::AlreadyPerformed: transaction already created

Para mais informações de como preencher a requisição, veja esse arquivo de teste.

Trabalhando com a resposta

A resposta de uma transação só estará disponível após ser feita chamada a create e pode conter dois elementos.

Erro na requisição

Caso o serviço tenha retornado algum erro, seu objeto de resposta vai conter um outro objeto chamado erro:

transaction.error.to_s
# => ERROR 002 - Credenciais inválidas
transaction.error.code
# => 002
transaction.error.message
# => Credenciais inválidas

Requisição efetuada com sucesso

Quanto a resposta da cielo for uma requisição válida, vamos ter elementos de retorno do xml

transaction.error.nil?
# => true
transaction.tid
# => 10069930690C6BA3A001

outros conteúdos do xml estão disponíveis como métodos: pan, status, authentication_url, order_data, payment_method

Consultando transações

Para consultar a situação de uma transação, você vai precisar do TID retornado pela Cielo quando você cria uma transação, veja um exemplo de como fazer uma consulta:

  query = Cielo::Query.new(spec) do |request|
    request.tid "10069930690C6BA3A001"
  end
  
  query.perform
  # => true
  
  query.tid
  # => 10069930690C6BA3A001

Estornando transações

Para estornar uma transação você vai precisar do TID retornado pela Cielo quando você cria uma transação, veja um exemplo:

  revoke = Cielo::Revoke.new(spec) do |request|
    request.tid "10069930690C6BA3A001"
  end
  
  revoke.perform
  # => true
  
  revoke.tid
  # => 10069930690C6BA3A001

Instrumentation

Algumas vezes precisamos coletar informações das requisições e respostas que enviamos e recebemos, para tal, pode ser usada a api de instrumentation do cielorb

class MyInstrumentation
  def notify_request(object, request, spec)
    # Aqui é possível recuperar o XML antes de ser enviado (request.to_xml), por exemplo.
  end
  
  def notify_response(object, response, spec)
    # Para recuperar o xml pode-se usar response.xml
  end
end

E por fim basta adicionar ao instrumentations

Cielo.observers << MyInstrumentation.new

Contribuindo

1. Fork it
2. Crie um branch com o nome da sua feature (git checkout -b my-new-feature)
3. Faça um commit (git commit -am 'Add some feature')
4. Envie os dados para seu fork (git push origin my-new-feature)
5. Crie um Pull Request