A maxiPago! recomenda que os Estabelecimento s mantenham em seu próprio banco de dados os detalhes das transações. Entendemos que isto nem sempre é possível, e por esta razão permitimos a sondagem de transações por período.
A busca por transações dentro de um período é especialmente útil para a produção de relatórios para plataformas onde não é possível manter um banco de dados local, como em um aplicativo para celular.
Para filtrar uma única transação deve-se usar o elemento <filterOptions/>, dentro da tag <request/>:
Consultar Lista de Pedidos – URLs Para Envio dos Dados
SANDBOX: https://testapi.maxipago.net/ReportsAPI/servlet/ReportsAPI
PRODUÇÃO: https://api.maxipago.net/ReportsAPI/servlet/ReportsAPI
Consultar Lista de Pedidos – Exemplo de Requisição
<?xml version="1.0" encoding="UTF-8"?>
<rapi-request>
<verification>
<merchantId>store-id</merchantId>
<merchantKey>store-key</merchantKey>
</verification>
<command>transactionDetailReport</command>
<request>
<filterOptions>
<period>range</period>
<pageSize>range</pageSize>
<startDate>range</startDate>
<endDate>range</endDate>
<startTime>range</startTime>
<endTime>range</endTime>
<orderByName>range</orderByName>
<orderByDirection>range</orderByDirection>
</filterOptions>
</request>
</rapi-request>
Retorno da Consulta
O retorno da chamada de consulta trará todas as informações da transação solicitada, ou uma lista de transações. As informações incluem dados como o status da transação, o valor do pedido, o ID do Pedido, ID da Transação e os códigos de retorno da adquirente.
Na eventualidade de o servidor postergar a sondagem do período, você receberá um token único que identifica aquela pesquisa. Guarde-o, pois ele será usado na re-sondagem dos dados.
O XML de retorno está dividido em três partes, <header/>, <resultSetInfo/> e <record/>:
<rapi-response>
<header>
...
</header>
<result>
<resultSetInfo>
<totalNumberOfRecords/>
<pageToken/>
<pageNumber/>
</resultSetInfo>
<records>
<record>
…
</record>
<record>
…
</record>
</records>
</result>
</rapi-response>
O elemento contém as informações da requisição de consulta, com os seguintes campos:
Já o elemento <resultSetInfo/> traz o total de registros encontrados e os dados do sistema de paginação:
O elemento contém os detalhes das transações individuais. Nem todos os campos são sempre retornados:
Utilizando o Sistema de Paginação
Ao puxar um relatório filtrado por período você provavelmente irá receber um número considerável de transações. Para evitar problemas de performance temos um sistema de paginação de resultados, que divide o número total de transações em várias páginas. É preciso puxar as demais páginas para obter todos os resultados.
O XML abaixo mostra um exemplo de resposta com 350 transações:
<rapi-response>
<header>
...
</header>
<result>
<resultSetInfo>
<totalNumberOfRecords>350</totalNumberOfRecords>
<pageToken>xyz35Hiua834</pageToken>
<pageNumber>1</pageNumber>
</resultSetInfo>
<records>
<record>
…
</record>
<record>
…
</record>
</records>
</result>
</rapi-response>
Para poder reaver os dados das demais páginas é preciso executar o comando transactionDetailReport novamente, passando outros parâmetros no elemento <filterOptions/>:
O XML de requisição para a sondagem da 3ª página de uma busca fica, então, desta forma:
<rapi-request>
<verification>
<merchantId>store-id</merchantId>
<merchantKey>secret-key</merchantKey>
</verification>
<command>transactionDetailReport</command>
<request>
<filterOptions>
<pageToken>xyz35Hiua834</pageToken>
<pageNumber>3</pageNumber>
</filterOptions>
</request>
</rapi-request>
Consulta em Massa
Dependendo da quantidade de registros solicitados a maxiPago! poderá aguardar um período de menor pico no servidor para executar a busca. Isto quer dizer que, nestes raros casos, o Estabelecimento deverá sondar novamente nossos servidores para verificar que a busca foi completada.
Nestes casos, a resposta da solicitação de envio de relatório é diferente. Os campos recebidos são:
O XML abaixo mostra um exemplo de uma resposta para estes casos:
<rapi-response>
<header>
<errorCode>0</errorCode>
<errorMsg/>
<command>transactionDetailReport</command>
<time>12-01-2011 11:27:54</time>
</header>
<result>
<pageToken>xyz35Hiua834</pageToken>
</result>
</rapi-response>
Sondando o Resultado de uma Busca em Massa
O Estabelecimento poderá posteriormente sondar a maxiPago! para ver se o relatório foi finalizado. Para isto é preciso executar o comando checkRequestStatus, cujo único campo aceito é o </requestToken>:
<rapi-request>
<verification>
<merchantId>store-id</merchantId>
<merchantKey>secret-key</merchantKey>
</verification>
<command>checkRequestStatus</command>
<request>
<filterOptions>
<requestToken>xyz35Hiua834</requestToken>
</filterOptions>
</request>
</rapi-request>
A resposta informará se o relatório foi finalizado ou se ainda está sendo processado pelo sistema. Os campos retornados pelo comando checkRequestStatus são:
Um exemplo do XML enviado na resposta é:
<rapi-response>
<header>
<errorCode>0</errorCode>
<errorMsg/>
<command>checkRequestStatusCommand</command>
<time>12-01-2011 11:27:54</time>
</header>
<result>
<statusMessage>REQUESTPROCESSED</statusMessage>
<resultSetInfo>
<totalNumberOfRecords>150</totalNumberOfRecords>
<pageToken>temp1300919096768.1</pageToken>
<processedTime>03-23-201115:24:56</processedTime>
</resultSetInfo>
</result>
</rapi-response>