Akatus

Esta gem é um cliente em Ruby para a API da Akatus.

Caso você esteja integrando a Akatus a uma aplicação Rails (versão 4.0.x), utilize diretamente a gem akatus-rails, que usa a gem akatus e ainda inclui funcionalidades adicionais específicas para Rails.

Todos os serviços básicos necessários para realizar a integração entre a sua aplicação de e-commerce e a sua conta Akatus já estão implementados.

Alguns serviços secundários (utilizados apenas para gerenciar a sua conta Akatus) serão implementados nas próximas versões.

• Pagamento com boleto bancário
  • Akatus::Services::Transaction#create
• Pagamento com cartão de crédito
  • Akatus::Services::Transaction#create
• Pagamento com TEF
  • Akatus::Services::Transaction#create
• Consulta de meios de pagamento disponíveis
  • Akatus::Services::PaymentOptions#available
  • Akatus::Services::PaymentOptions#available_with_installments
• Simulação de parcelamento
  • Akatus::Services::Installments#calculate

• Cadastro de conta bancária
• Cadastro de conta empresarial
• Cadastro de conta vendedor
• Consulta de conta bancária
• Consulta de tipos de comércio
• Envio de documentos
• Consulta de status de transação
• Estorno

Adicione esta linha ao seu Gemfile:

gem 'akatus'

Em seguide, execute:

$ bundle

Se não quiser utilizar o Gemfile, simplesmente execute:

$ gem install akatus

Toda transação, seja com boleto bancário, cartão de crédito ou TEF, requer as mesmas informações básicas:

• Conta Akatus recebedora
• Informações sobre o comprador
  • Nome
  • Email
  • Endereço (ou endereços)
  • Telefone (ou telefones)
• Informações sobre os produtos
• Forma de pagamento

Portanto, em primeiro lugar é necessário criar os objetos que contêm estas informações, como foi feito abaixo.

Note que alguns campos possuem restrições de valor ou formato. Estas restrições não são verificadas pela gem, você precisará consultá-las no site da Akatus.

require 'akatus'

# Configuração da conta recebedora

Akatus.config.email = "email-da-conta-akatus@exemplo.com"
Akatus.config.api_key = "api-key-da-conta-akatus"

# Informações do comprador.

address = Akatus::Address.new({
  :type               => 'entrega',
  :street             => 'Rua Labib Marrar',
  :number             => '129',
  :neighborhood       => 'Jardim Santa Cruz',
  :city               => 'São Paulo',
  :state              => 'SP',
  :country            => 'BRA',
  :postal_code        => '04182040',
  :additional_details => 'Apto. 33'
})

payer = Akatus::Payer.new({
  :name    => 'Jose Antonio',
  :email   => 'ze@antonio.com.br',
  :address => address,
  :phone   => Akatus::Phone.new({
    :type   => 'comercial',
    :number => '1199999999'
  })
})

# Informações dos produtos.

item1 = Akatus::Item.new({
  :reference     => 'ABC1234567',
  :description   => 'Caixa de bombons sortidos',
  :quantity      => 10,
  :price         => BigDecimal.new('32.2'),
  :weight        => BigDecimal.new('2.25'),
  :shipping_cost => 9,
})

item2 = Akatus::Item.new({
  :reference     => 'EFG',
  :description   => 'Camiseta',
  :quantity      => 1,
  :price         => BigDecimal.new('9.99')
})

Quase pronto! Agora, é só escolher uma forma de pagamento e criar o pagamento:

# Boleto bancário
payment_method = Akatus::BoletoBancario.new

# TEF. Os valores válidos para `brand` dependem das configurações da
# sua conta, e podem ser obtidos com o serviço de meios de pagamento
# (Akatus::Services::PaymentOptions.available).
payment_method = Akatus::ElectronicFundsTransfer.new({
  :brand => 'tef_itau'
})

# Cartão de crédito
payment_method = Akatus::CreditCard.new({
  :brand         => 'cartao_master',
  :number        => 'NUMERO DO CARTAO DE CREDITO',
  :security_code => '643',
  :installments  => 1,
  :expiration    => '03/2015',
  :holder_name   => 'NOME IMPRESSO NO CARTAO',
  :holder_cpf    => 'CPF DO PORTADOR',
  :holder_phone  => 'TELEFONE DO PORTADOR'
})

payment = Akatus::Payment.new({
  :payer          => payer,
  :items          => [ item1, item2 ],
  # Um valor significativo para o seu e-commerce
  :reference      => 'order#0001',
  # Uma das formas de pagamento mostradas acima
  :payment_method => payment_method
})

Finalmente, basta enviar a requisição para a Akatus:

Akatus::Services::Transaction.create(payment)

Se tudo deu certo, o objeto payment agora contém novas informações, de acordo da forma de pagamento utilizada:

• No caso de boleto, o link para geração do boleto pode ser acessado como payment.url;
• No caso de TEF, o link para redirecionamento ao banco pode ser acessado como payment.url;
• No caso de cartão de crédito, o status da transação estará armazemado em payment.status.

Se ocorreu algum erro de validação do lado da Akatus, o código acima lançará uma exceção do tipo Akatus::UnprocessableEntityError, com a mensagem de erro.

Por exemplo, um erro seria não configurar corretamente o email e API key da sua conta Akatus:

begin
  Akatus.config.email = 'invalido'

  # Supondo que `payment` é o mesmo objeto criado acima
  Akatus::Services::Transaction.create(payment)
rescue Akatus::UnprocessableEntityError => exc
  exc.message # => "conta não encontrada"
end

• Veja a Aplicação Rails de exemplo.
• Você também pode ver os testes (em spec/) para alguns exemplos básicos.

1. Crie um fork da gem
2. Crie uma feature branch (git checkout -b my-new-feature)
3. Faça um commit das suas alterações (git commit -am 'Add some feature')
4. Envie para o GitHub (git push origin my-new-feature)
5. Crie um novo pull request