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 |
Headers (Opcional)
Utilizar esses headers em caso de autenticação direto com as credenciais do cedente:
| Nome | Descrição | Exemplo |
| Content-Type | Indica o tipo de arquivo | application/json |
| cnpj-cedente | CNPJ do Cedente | 01001001000113 |
| token-cedente | Token do Cedente | f22b97c0c9a3d41ac0a3875aba69e5aa1 |
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": "78",
"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,
"PagamentoValorOutrosCreditos": "0,00",
"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.
Para os retornos que possuem boletos de cedentes distintos (ocorre em caso de matriz e filial que utiliza a mesma conta), será retornado juntamente com o idintegracao o CNPJ do cedente (cedentecpfcnpj),
Exemplo do retorno:
{
"_status": "sucesso",
"_dados": {
"situacao": "PROCESSADO",
"mensagem": "",
"processados": 2,
"titulos": [
{
"idIntegracao": "HyNyGOtj-",
"cedentecpfcnpj": "99999999999999"
},
{
"idIntegracao": "B1lBl1v5j-",
"cedentecpfcnpj": "99999999999998"
}
],
"titulosNaoConciliados": [ ]
}
}
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 laço de repetição, que refaz a consulta caso a situação seja igual a "Processando", com um delay de pelo menos 5 segundos entre cada consulta.
Isto é importante pois o tempo de processamento depende diretamente da quantidade de boletos dentro do arquivo de retorno.
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.