O objetivo da Consulta é que você receba um json contendo todos os campos de seu boleto.
Neste json, você poderá consultar a Situação em que este boleto se encontra, consultar as informações de pagamento, motivo de erros e é a interface utilizada para que você atualize seu sistema com base nas informações que nós te retornamos.
Um boleto pode ter 7 situações diferentes, que podem ser verificadas neste link.
Para verificar quais campos são retornados nesta consulta, clique aqui.
OBS: Para verificar o status da API, não é recomendo realizar várias consultas por minuto, mas recomendamos o uso da rota http://plugboleto.com.br/status Essa rota permite que você obtenha informações atualizadas sobre o status da API em tempo real.
GET
Homologação:
https://homologacao.plugboleto.com.br/api/v1/boletos
Produção:
https://plugboleto.com.br/api/v1/boletos
Headers
| Nome | Descrição | Exemplo |
| cnpj-sh | CNPJ da Software House | 01001001000113 |
| token-sh | Token da Software House | f22b97c0c9a3d41ac0a3875aba69e5aa |
| cnpj-cedente | CNPJ do Cedente | 01001001000113 |
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 |
Status dos boletos
Segue abaixo uma tabela no qual
| Status | Significado |
| SALVO | Indica que o boleto está em processamento pela API ou aguardando o processamento do banco (Web Service). |
| FALHA | Refere-se a um boleto com problemas identificados pela Tecnospeed, que podem estar relacionados ao banco. |
| EMITIDO | O boleto foi gerado na API, mas ainda não foi registrado no banco. |
| PENDENTE_RETENTATIVA | Esta situação irá ocorrer quando houve alguma falha no momento de registrar o boleto, e será realizado uma nova tentativa de registro em 1 minuto. (Web Service). |
| REGISTRADO | O boleto foi registrado no banco e está pronto para pagamento. |
| REJEITADO | O boleto foi rejeitado diretamente pelo banco. |
| BAIXADO | O boleto foi cancelado no banco. |
| LIQUIDADO | O boleto foi pago. |
OBS: Incluiremos uma nota destacando que, sempre que o boleto retornar com status FALHA ou REJEITADO, o cliente deve verificar o campo "motivo" retornado pela API. Esse campo fornecerá informações específicas sobre o motivo da falha ou rejeição, auxiliando na resolução de problemas.
Personalizando a consulta
A consulta acima retorna todos os boletos daquele cedente, paginando de acordo com o limite da API. Entretanto, é possível utilizar os parâmetros da URL (querystring) para personalizar a consulta. Veja nos exemplos abaixo:
PAGINAÇÃO
Utilize os parâmetros limit (para limitar a quantidade) e skip (para pular registros).
http://homologacao.cobrancabancaria.tecnospeed.com.br/api/v1/boletos?limit=5
http://homologacao.cobrancabancaria.tecnospeed.com.br/api/v1/boletos?sort=TituloNumeroDocumento,-situacao
ORDENAÇÃO
Utilize o parâmetro sort e adicione os campos desejados para a ordenação, adicionando - como prefixo para utilizar ordem decrescente. Caso haja mais de um campo, utilize , como separador.
Utilize os parâmetros limit (para limitar a quantidade) e skip (para pular registros).
https://homologacao.cobrancabancaria.tecnospeed.com.br/api/v1/boletos?sort=situacao
https://homologacao.cobrancabancaria.tecnospeed.com.br/api/v1/boletos?skip=10
https://homologacao.cobrancabancaria.tecnospeed.com.br/api/v1/boletos?limit=5&skip=5
FILTRO
Para fazer uma consulta utilizando filtros adicione nos parâmetros de URL os campos disponíveis para consulta que são "idintegracao, titulodataemissao, titulodatavencimento, titulonumerodocumento, sacadocpfcnpj, sacadonome e situacao". No filtro é possivel fazer uma comparação (Maior ou menor) para isso depois do sinal de = deve se informar um dos operadores <, >, <= e >=. Um exemplo TituloDataEmissao=>=2017/12/26 (maior ou igual). Para buscar por um conteúdo parcial utilize o prefixo $. É possível adicionar mais de um filtro por campo, repetindo o campo desejado nos parâmetros de URL.
Para filtrar os boletos de uma única não precisa ser utilizado as condicionais apenas passar a data desejada. Exemplo: TituloDataEmissao=2017/12/26, dessa forma será retornado todos os boletos da data informada.
| Campos disponíveis para filtro na querystring: |
| idintegracao |
| titulodataemissao |
| titulodatavencimento |
| titulonumerodocumento |
| sacadocpfcnpj |
| sacadonome |
| situacao* |
| TituloCodigoReferencia |
| PagamentoData |
| titulonossonumero |
| id_convenio |
| codConta |
| contacodigobanco |
*Possiveis situações de um boleto: SALVO, EMITIDO, FALHA, BAIXADO, REGISTRADO, LIQUIDADO, REJEITADO, PENDENTE_RETENTATIVA
https://homologacao.cobrancabancaria.tecnospeed.com.br/api/v1/boletos?situacao=EMITIDO
https://homologacao.cobrancabancaria.tecnospeed.com.br/api/v1/boletos?id=>1
https://homologacao.cobrancabancaria.tecnospeed.com.br/api/v1/boletos?SacadoNome=$jose&SacadoNome=$silva&situacao=BAIXADO
https://homologacao.cobrancabancaria.tecnospeed.com.br/api/v1/boletos?IdIntegracao=HylCKRX7be,H1leBL4XWx
https://homologacao.cobrancabancaria.tecnospeed.com.br/api/v1/boletos?PagamentoData=2020/08/01&TituloDataEmissao=2020/07/01
https://homologacao.cobrancabancaria.tecnospeed.com.br/api/v1/boletos?contacodigobanco=341
Retorno
Exemplo de retorno:
{
"_status": "sucesso",
"_dados": [
{
"IdIntegracao": "HkgMri2cHl",
"SacadoCPFCNPJ": "28436161661",
"SacadoEmail": "email@sacado.com",
"SacadoEnderecoNumero": "987",
"SacadoEnderecoBairro": "Centro",
"SacadoEnderecoCEP": "87098765",
"SacadoEnderecoCidade": "Maringá",
"SacadoEnderecoComplemento": "Fundos",
"SacadoEnderecoLogradouro": "Rua teste, 987",
"SacadoEnderecoPais": "Brasil",
"SacadoEnderecoUF": "PR",
"SacadoNome": "Teste de Souza",
"SacadoTelefone": "4499999999",
"TituloDataDesconto": "05/01/2020 00:00:00",
"TituloDataEmissao": "01/01/2020 00:00:00",
"TituloDataVencimento": "01/01/2020 00:00:00",
"TituloDataMulta": null,
"PagamentoData": null,
"PagamentoDataCredito": null,
"TituloPrazoProtesto": "30",
"TituloMensagem01": "Juros de 0,01 ao dia",
"TituloMensagem02": "Nao receber apos 30 dias de atraso",
"TituloMensagem03": "Titulo sujeito a protesto apos 30 dias",
"TituloOcorrencias": [
{
"codigo": "02",
"mensagem": "Tarifa de Manutenção de Título Vencido",
"criado": "29/06/2018 18:45:22",
"atualizado": "29/06/2018 18:45:22"
},
{
"codigo": "03",
"mensagem": "Liquidação no Guichê de Caixa em Dinheiro",
"criado": "29/06/2018 18:45:22",
"atualizado": "29/06/2018 18:45:22"
},
{
"codigo": "06",
"mensagem": "Movimento: Liquidação",
"criado": "29/06/2018 18:45:22",
"atualizado": "29/06/2018 18:45:22"
},
{
"codigo": "28",
"mensagem": "Movimento: Débito de Tarifas/Custas",
"criado": "29/06/2018 18:45:22",
"atualizado": "29/06/2018 18:45:22"
}
],
"TituloMovimentos": [
{
"codigo": "28",
"mensagem": "Movimento: Débito de Tarifas/Custas",
"data": "04/05/2018 00:00:00",
"ocorrencias": [
{
"codigo": "02",
"mensagem": "Tarifa de Manutenção de Título Vencido"
}
]
},
{
"codigo": "06",
"mensagem": "Movimento: Liquidação",
"data": "04/05/2018 00:00:00",
"ocorrencias": [
{
"codigo": "03",
"mensagem": "Liquidação no Guichê de Caixa em Dinheiro"
}
]
}
],
"TituloNossoNumero": "1",
"TituloNumeroDocumento": "01012020",
"TituloOrigemDocumento": null,
"PagamentoRealizado": null,
"TituloValorJuros": "0,01",
"TituloInstrucao1": "04",
"TituloInstrucao2": "05",
"PagamentoValorCredito": "0,00",
"TituloValorDesconto": "0,01",
"TituloValorOutrosAcrescimos": "0,00",
"TituloValorMulta": "0,00",
"TituloValorMultaTaxa": "0,00",
"PagamentoValorPago": "0,00",
"PagamentoValorTaxaCobranca": "0,00",
"TituloValorAbatimento": "0,00",
"PagamentoValorOutrasDespesas": "0,00",
"PagamentoValorIOF": "0,00",
"PagamentoValorOutrosCreditos": "0,00",
"TituloValor": "0,02",
"situacao": "LIQUIDADO",
"impressao_visualizada": false,
"motivo": null,
"PagamentoValorDesconto": "0,00",
"PagamentoValorAcrescimos": "0,00",
"PagamentoValorAbatimento": "0,00",
"UrlBoleto": "https://homologacao.plugboleto.com.br/api/v1/boletos/impressao/HkgMri2cHl",
"CedenteAgencia": "4321",
"CedenteAgenciaDV": null,
"CedenteCodigoBanco": "341",
"CedenteConta": "54321",
"CedenteCarteira": "109",
"CedenteNumeroConvenio": "321"
}
],
"_meta": {
"_itens_por_pagina": 20,
"_paginacao": {
"_proximo": false,
"_anterior": false
},
"_total": 1
}
}
Exemplo de retorno com erro:
{
"_status": "sucesso",
"_mensagem": "Nenhum registro encontrado",
"_dados": [],
"_meta": {
"_itens_por_pagina": 20,
"_paginacao": {
"_proximo": false,
"_anterior": false
},
"_total": 0
}
}
Se ao consultar o IdIntegracao a situação do boleto for retornada como EMITIDO, podemos seguir o fluxo de emissão, e ir para o próximo passo, que é realizar a geração do PDF.
O que são movimentos e ocorrências?
Os movimentos nada mais são do que a mensagem encaminhada pelo banco sobre um determinado boleto, com uma própria movimentação do título, como por exemplo.
O Boleto encontrava-se como EMITIDO e o status foi alterado para REGISTRADO, desta forma nos movimentos do título irá constar:
TituloMovimentos": [
{
"codigo": "02",
"mensagem": "Movimento: Entrada Confirmada",
"data": "30/08/2021 00:00:00",
"taxa": "1,59",
"ocorrencias": [
{
"codigo": "76",
"mensagem": "Pagador Eletrônico DDA- PRe motivo somente será disponibilizado no arquivo retorno para as empresas cadastradas nessa condição"
}
]
}
Onde "02" seria referente ao código de movimento de entrada confirmada.
Porém ao verificarmos, dentro de um movimento consta uma ocorrência, que neste caso acabou sendo o código "76". Atualmente nem todos os bancos acatam os mesmos códigos disponibilizados pela Febraban, pois os mesmos podem possuir alguns códigos disponibilizados particularmente pelo próprio banco.
Simplificando:
O Movimento é uma mensagem de mudança ou como próprio nome já diz, "Movimento" de algo do boleto (Registro, Alteração acatada ou rejeitada, Liquidação), enquanto a ocorrência deve-se ao motivo do mesmo.
Mas e quando ao consultar o boleto, não consta o código de ocorrência?
Conforme citamos acima, alguns bancos não possuem os mesmos códigos disponibilizados pela Febraban, portanto caso o banco tenha disponibilizado o arquivo de retorno onde consta uma ocorrência, porém a mesma acabou não sendo apresentada ao consultar o boleto, basta nos informar através dos canais de atendimento pois provavelmente o banco acabou atualizando o manual, e com isso iremos atualizar nossa aplicação.
Comentários
0 comentário
Por favor, entre para comentar.