Acessando Transações no PayPal com Perl

November 29th, 2013

Category: Desenvolvimento, Developers, Perl

Tagged with: , , ,

Este tutorial mostra como fazer um script em Perl que captura uma lista de pagamentos recebidos em uma conta PayPal. A lista é salva em um arquivo texto com delimitadores (CSV), podendo então ser importada em um editor de planilhas para a criação de relatórios gráficos e tabulares.


Para obter o resultado desejado, é necessário garantir que o Perl instalado tenha os módulos necessários, bem como configurar um token de acesso na conta PayPal. Esse token vai ser salvo no script mesmo. Dessa forma, não recomendo a publicação dele em um site, ou seja, o script feito aqui é para uso local, de modo a garantir que as credenciais de acesso à conta PayPal não fiquem expostas na Internet.

Configurando o Perl

Os seguintes módulos do Perl devem ser instalados:

  • DateTime
  • Mozilla::CA
  • Business::PayPal::API

Para adicionar módulos no Perl, a forma mais fácil é usar seu instalador, através do comando:

sudo perl -MCPAN -e shell

Entrando em modo interativo, basta chamar o comando install para cada um dos módulos. Caso haja alguma dependência, ela será instalada automaticamente.

cpan[]> install DateTime
cpan[]> install Mozilla::CA
cpan[]> install Business::PayPal::API

O bundle de certificado Mozilla é necessário pois a conexão com o web service do PayPal é feita por HTTPS e o módulo Perl para a API PayPal faz a verificação do PEER. Caso não o tenha instalado, o script poderá receber um erro do tipo “Can’t verify SSL peers without knowning which Certificate Authorities to trust”.

Gerando Credenciais no PayPal

É preciso uma forma de permitir o script acessar as informações da conta do PayPal. Isso pode ser feito de diversas formas. Aqui usamos o método de PayPal API Signature, ou também chamado PayPal API Token.

No painel da conta PayPal, navegue para Profile->More Options->My selling tools->Selling online-> API access. Veja a figura:

PayPal API Access Option

Acessando a configuração de acesso via API no painel da conta PayPal

Clique em Update à direita.

Na tela seguinte selecione a segunda opção: Request API Credentials

Request API Credentials

Requisitando Credenciais de API no PayPal

Entre escolher API Signature ou Certificate, escolha Signature. Veja na figura abaixo a seleção.

API Signature Option

Escolhendo API Signature

Finalmente, um usuário, senha e assinatura da API PayPal são gerados. Mantenha essa janela aberta para copiar depois esses dados.

As Credenciais da API PayPal

As Credenciais da API PayPal

O Script Perl

Para criar o script, use o editor da sua preferência. Se você usa Mac, recomendo o MVIM.

Comece o script carregando os módulos.

#!/usr/bin/perl
use DateTime;
use Business::PayPal::API qw(TransactionSearch GetTransactionDetails);
my $entry;

A variável $entry vai ser usada posteriormente para montar a saída formatada de cada linha, com os delimitadores.
Nesse exemplo vou incluir a funcionalidade de informar um ano e mês para a pesquisa. Assim, o script retorna apenas as transações realizadas no período informado. Adicionamos, então, a linha para capturar o ano e mês como parâmetros passados para o script na linha de comando.

my ( $yearComponent, $monthComponent ) = @ARGV;

Com o parâmetros recebidos, calculamos a data de início e a data final para passar posteriormente na consulta. Como a ideia é pegar o mês todo, a data inicial será dia 1 e a data final será o último dia do mês.

my $startDate = DateTime->new(
        year  => $yearComponent,
        month => $monthComponent,
        day   => 1,
);

my $endDate = DateTime->last_day_of_month(
        year  => $startDate->year,
        month => $startDate->month
);

O passo seguinte é instanciar um objeto de acesso com as credenciais. Elas devem ser copiadas da última tela mostrada no processo de requisição de credenciais.

my $pp = new Business::PayPal::API(
        Username  => 'xxxxxxx_api1.xxxxxxxxx.com.br',
        Password  => 'XXXXXXXXXXXXXX',
        Signature => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        sandbox   => 0
);

E fazer a consulta. O resultado vai para um hash. Abrimos um loop para varrer esse hash, pegando cada transação retornada.

my $records = $pp->TransactionSearch(
        StartDate => $startDate . 'T00:00:00Z',
        EndDate   => $endDate . 'T23:59:59Z',
        TransactionClass => 'Received',
        Status    => 'Success'
);

for my $rec (@$records) {

Repare que estamos filtrando também o tipo e status das transações a pesquisar. Queremos aqui apenas os pagamentos recebidos na conta, por isso o filtro TransactionClass => ‘Received’. E também nos interessa somente os que foram finalizados com sucesso, daí o outro filtro Status => ‘Success’. Outros valores possíveis para TransactionClass são: All, Sent, e Refund. Os nomes são auto-explicativos. Veja a explicação completa dos critérios de busca em Consulta PayPal API – Critérios de Busca.

Nem todos os detalhes das transações são retornados no hash da consulta. Por isso vou incluir para cada registro retornado, uma consulta por detalhes completos. Isso é opcional, para a maioria dos casos a lista geral retorna informações suficientes.

for my $rec (@$records) {
        my %response =
          $pp->GetTransactionDetails(
               TransactionID => $rec->{TransactionID}
          );

No loop, $rec contém a transação corrente, obtida da varredura sequencial da lista completa. $rec, por sua vez, contém uma série de pares key->value e um deles é o ID da transação. Então $rec->{TransactionID} pode ser usado na consulta por detalhes de uma transação no método GetTransactionDetails.

Agora podemos começar a criar as linhas com os dados delimitados.

$entry = substr( $rec->{Timestamp}, 0, 10 )	. ',';
	$entry .= '"' . $rec->{PayerDisplayName}	. '",';
        $entry .= '"' . $rec->{Payer}			. '",';
        $entry .= '"' . $response{InvoiceID}		. '",';
        $entry .= $rec->{GrossAmount}			. ',';
        $entry .= $rec->{FeeAmount}			. ',';
        $entry .= $rec->{NetAmount}		. ',';
        $entry .= '"' . $rec->{TransactionID}		. '"';
        $entry .= "\n";

Repare que o InvoiceID vem da consulta detalhada da transação. É um campo importante, pois é nele que você pode inserir o número do pedido da sua loja durante o processo de pagamento. Desta forma, pode identificar no seu sistema a qual pedido ou produto se refere este pagamento. Outro campo que pode ser interessante é o PII_Name, que retorna a descrição do produto/serviço.

Para completar, falta apenas imprimir cada linha no loop:

print $entry;

O script completo deve ficar assim:

#!/usr/bin/perl
use DateTime;
use Business::PayPal::API qw(TransactionSearch GetTransactionDetails);
my $entry;
my ( $yearComponent, $monthComponent ) = @ARGV;
my $startDate = DateTime->new(
        year  => $yearComponent,
        month => $monthComponent,
        day   => 1,
);

my $endDate = DateTime->last_day_of_month(
        year  => $startDate->year,
        month => $startDate->month
);
my $pp = new Business::PayPal::API(
        Username  => 'xxxxxxx_api1.xxxxxxxxx.com.br',
        Password  => 'XXXXXXXXXXXXXX',
        Signature => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        sandbox   => 0
);
my $records = $pp->TransactionSearch(
        StartDate => $startDate . 'T00:00:00Z',
        EndDate   => $endDate . 'T23:59:59Z',
        TransactionClass => 'Received',
        Status    => 'Success'
);

for my $rec (@$records) {
        my %response =
          $pp->GetTransactionDetails(
               TransactionID => $rec->{TransactionID}
          );
	$entry = substr( $rec->{Timestamp}, 0, 10 )	. ',';
	$entry .= '"' . $rec->{PayerDisplayName}	. '",';
        $entry .= '"' . $rec->{Payer}			. '",';
        $entry .= '"' . $response{InvoiceID}		. '",';
        $entry .= $rec->{GrossAmount}			. ',';
        $entry .= $rec->{FeeAmount}			. ',';
        $entry .= $rec->{NetAmount}		. ',';
        $entry .= '"' . $rec->{TransactionID}		. '"';
        $entry .= "\n";
	print $entry;
}

Para executar o script pode ser necessário configurar o atributo de execução do arquivo:

chmod 755 txnpaypal.pl

Lembre-se que o script exige a passagem de dois parâmetros, o ano e o mês. Veja um exemplo abaixo:

./txnpaypal.pl 2013 11

Não fizemos aqui o tratamento de erro para o caso do script ser chamado sem parâmetros ou com parâmetros inválidos, como mês 13 por exemplo. Não é o foco deste tutorial.

Veja um exemplo da saída:


2013-11-19,"XXXX XXX","x@x.com","P002",346.10,-22.21,323.89,"XXXX"
2013-11-16,"XXXX XXX","x@x.com","P001",29.95,-2.52,27.43,"XXXX"
2013-11-12,"XXXX XXX","x@x.com","P001",29.95,-2.52,27.43,"XXXX"
2013-11-04,"XXXX XXX","x@x.com","P001",29.95,-2.52,27.43,"XXXX"

Os valores em cada linha são, respectivamente, valor bruto, taxas pagas ao PayPal, e valor líquido. O nome e o email de quem enviou o pagamento são o segundo e terceiro itens. O que aparece no exemplo como P00X é o número do pedido caso você tenha usado para montar a requisição de pagamento, e o último código é o número da transação no PayPal.
Para salvar o resultado em um arquivo basta redirecionar a saída do script:

./txnpaypal.pl 2013 11 > recebimentos.csv


Helder Garcia

1 comment

  • Fabiano says:

    Helder blz..cara vc faria algum tutorial para iniciante.??


  • Leave a Reply

    Your email address will not be published. Required fields are marked *