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:

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

Requisitando Credenciais de API no PayPal

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

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

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.

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.

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.

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.

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

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.

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.

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:

O script completo deve ficar assim:

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

Google+

Helder Garcia