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 gemakatus
e ainda inclui funcionalidades adicionais específicas para Rails.
Serviços implementados
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.
Implementados
- 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
Previstos
- 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
Instalação
Adicione esta linha ao seu Gemfile:
gem 'akatus'
Em seguide, execute:
$ bundle
Se não quiser utilizar o Gemfile, simplesmente execute:
$ gem install akatus
Exemplo de uso
Criando uma transação
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
- 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 protected]"
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 => '[email protected]',
: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. # => "conta não encontrada"
end
Mais exemplos
- Veja a Aplicação Rails de exemplo.
- Você também pode ver os testes (em
spec/
) para alguns exemplos básicos.
Contribuindo
- Crie um fork da gem
- Crie uma feature branch (
git checkout -b my-new-feature
) - Faça um commit das suas alterações (
git commit -am 'Add some feature'
) - Envie para o GitHub (
git push origin my-new-feature
) - Crie um novo pull request