Após fazermos o upload do arquivo de retorno, chegou a hora de consultar o protocolo obtido para efetivamente, receber o resultado do processamento de seus boletos.
Para fazermos essa consulta, vamos precisar do protocolo gerado na requisição anterior.
GET
A solicitação é feita através de uma requisição GET. A rota chamada deve ter a seguinte URL:
Homologação:
https://homologacao.plugboleto.com.br/api/v1/retornos/:protocolo
Produção:
https://plugboleto.com.br/api/v1/retornos/:protocolo
*Aqui temos um exemplo da URL completa, informando um número de protocolo:
Headers
Nome | Descrição | Exemplo |
cnpj-sh | CNPJ da Software House | 01001001000113 |
cnpj-cedente | CNPJ da Cedente | 01001001000113 |
token-sh | Token da Software House | f22b97c0c9a3d41ac0a3875aba69e5aa |
Retorno
Exemplo de retorno:
{
"_status": "sucesso",
"_dados": {
"situacao": "PROCESSADO",
"mensagem": "",
"processados": 2,
"titulos": [
{
"idIntegracao": "HyNyGOtj-"
},
{
"idIntegracao": "B1lBl1v5j-"
}
],
"titulosNaoConciliados": [
{
"Ocorrencias": [
"Movimento: Liquidação normal"
],
"CodigosOcorrencias": [],
"CodigoMovimento": "06",
"TituloNossoNumero": "03300000780",
"TituloNossoNumeroOriginal": "3300000780",
"TituloDataVencimento": "02/10/2017",
"PagamentoValorPago": "427,81",
"PagamentoValorCredito": "0,00",
"PagamentoValorTaxaCobranca": "0,00",
"PagamentoValorAcrescimos": "0,00",
"PagamentoData": "20/09/2017",
"PagamentoDataCredito": "20/09/2017",
"PagamentoRealizado": true,
"TituloNumeroDocumento": "1020"
}
]
}
}
A resposta acima retorna dentro do objeto titulos todos os Ids de integração que foram conciliados com aquele arquivo de retorno. Agora, o ideal é fazer a consulta desses Ids para verificar o status de cada boleto dentro da base.
O objeto titulosNaoConciliados retorna os dados dos boletos que estão presentes no arquivo de retorno, mas que não estão em nossa base (isso acontece quando o cedente emite o boleto direto pelo banco). Você pode usar esses dados para obter um controle maior em seu sistema.
Exemplo de retorno com erro:
{
"_status": "erro",
"_mensagem": "Retorno não encontrado."
}
Exemplo de retorno 'em processamento':
{
"_status": "sucesso",
"_mensagem": "Solicitação pendente de processamento",
"_dados" : {
"situacao": "PROCESSANDO"
}
}
O status acima indica que o arquivo ainda está em processamento na nossa API. Isso geralmente acontece quando o arquivo de retorno é grande, e contém muitos boletos para serem conciliados. Fique tranquilo, se você tiver esse retorno basta refazer a consulta (passando o mesmo protocolo informado inicialmente) até que o arquivo seja devolvido.
Uma implementação interessante neste caso, é colocar este método de consulta do protocolo em um While, que refaz a consulta caso a situação seja igual a "Processando", com um delay de pelo menos 5 segundos entre cada consulta.
Comentários
2 comentários
Esses pontos no final de cada campo, estão corretos? isso significa que eles são Strings, e não podem ser formatados?
Olá Lennon,
Estamos migrando a nossa documentação para este portal, e por algum motivo foi adicionado os pontos no final do campo, porém, nossa API não retorna neste formato, Obrigado pelo posicionamento. Estarei providenciando uma correção.
Por favor, entre para comentar.