Consultando um boleto

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 é recomendado 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:

 Produção:

 

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).

 

*limit máximo = 1000

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).

 

 

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:	Significado:
idintegracao	Identificador único do título retornado na inclusão do boleto - Ex: 2RS0O1ED3
titulodataemissao	Data em que o boleto foi emitido
titulodatavencimento	Data de vencimento do boleto
titulonumerodocumento	Número de Documento/Seu Número
sacadocpfcnpj	CPF/CNPJ do Pagador
sacadonome	Nome do Pagador
situacao*	Situação do Boleto (Situações disponíveis)
TituloCodigoReferencia	Campo livre, valor de identificação secundária - Ex: 1234
PagamentoData	Data de Pagamento do Boleto - Ex:
titulonossonumero	Nosso Número do Boleto - Ex: 1234
id_convenio	ID numérico do Convênio (coletado na consulta do convênio na API)
codConta	ID da Conta numérico da Conta (coletado na consulta da conta na API)
contacodigobanco	Código do Banco - Ex: 341
atualizado	Data da última atualização - AAAA-MM-DD
conta	Número da conta sem o DV
conta_dv	DV da conta

*Possiveis situações de um boleto: SALVO, EMITIDO, FALHA, BAIXADO, REGISTRADO, LIQUIDADO, REJEITADO, PENDENTE_RETENTATIVA

Não há um limite exato de quantos boletos são possíveis de consultar de uma vez, existe apenas um limite de caracteres permitidos na rota, que nesse caso seria 2048 caracteres. Considerando a consulta por ID integração, por exemplo, que contém 9 caracteres, juntando vírgula e todos outros caracteres fixos, é possível definir um limite seguro de 180 IDs por vez para consulta.

 

 

Retorno

 

Exemplo de retorno:

 

 

Exemplo de retorno com erro:

 

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.