Pular para o conteúdo
API Boleto Cloud

Situação do boleto × arquivo de retorno

O arquivo de retorno é o evento — o que o banco informou naquele arquivo, naquele dia — e a consulta de situação (GET /boletos/{token}/situacao) é o estado consolidado do boleto na plataforma. A API não envia notificação ao seu sistema.

Conciliar pagamentosO pagador paga o boleto no banco. O banco informa o pagamento ao Boleto Cloud, conforme o canal da conta, e a situação do boleto é atualizada. Dois fluxos partem do servidor do seu sistema. Consultar a situação, no Plano Personalizado: HTTP GET /boletos/{token}/situacao com Authorization: Basic …; resposta 200 (OK), com situacao PAGO e pagamento contendo data, valor e dataCredito. Também é possível consultar pelo seu identificador em GET /boletos/controle/{tokenControleUsuario}/situacao. Processar o arquivo de retorno, nos planos Grátis e Personalizado: seu sistema baixa o arquivo de retorno do banco e envia o CNAB em multipart por HTTP POST /arquivos/cnab/retornos; resposta 201 (Criado), com titulos, ocorrencias de situacao LIQUIDACAO e info contendo valorPago e dataDePagamento. Cada resposta volta ao servidor e o navegador do seu sistema mostra o boleto como Pago. Setas cheias indicam requisições e sequência; tracejadas indicam respostas. A API não envia notificação ao seu sistema: consulte a situação ou processe o retorno.Conciliar pagamentosO pagador pagao boleto no bancoO banco informa o pagamentoao Boleto Cloud(conforme o canal da conta)A situação doboleto é atualizada1. Consultar a situaçãoPlano: PersonalizadoSeu sistemaServidorHTTP GET /boletos/{token}/situacaoAuthorization: Basic …API BoletoCloud200 (OK){ "situacao": "PAGO", "pagamento": { "data": …, "valor": …, "dataCredito": … } }Também pelo seu identificador:GET /boletos/controle/{tokenControleUsuario}/situacaoSeu sistemasistema.com/boletosBoletoSituaçãoPago2. Processar o arquivo de retornoPlanos: Grátis e PersonalizadoSeu sistema baixa o arquivo de retorno do banco e envia:Seu sistemaServidorHTTP POST /arquivos/cnab/retornosAuthorization: Basic …Arquivo CNAB · multipartAPI BoletoCloud201 (Criado){ "titulos": [ { "ocorrencias": [ { "situacao": "LIQUIDACAO", "info": { "valorPago": …, "dataDePagamento": … } } ] } ] }Seu sistemasistema.com/boletosBoletoSituaçãoPagoA API não envia notificação ao seu sistema:consulte a situação ou processe o retorno.

O que é cada um

Seção intitulada “O que é cada um”

Arquivo de retorno. Ocorrências daquele arquivo, naquele dia: o que o banco informou. O processamento está em Processar retorno. A visão do arquivo está em Retorno CNAB.

Consulta de situação. O estado consolidado (registro, pagamento, baixa, protesto e Pix) do boleto na plataforma. A rota é GET /boletos/{token}/situacao. Com o identificador informado na criação, a mesma consulta é GET /boletos/controle/{tokenControleUsuario}/situacao. Veja Consultar situação.

Quando usar cada um

Seção intitulada “Quando usar cada um”
Caminho Para que serve Plano
Processar retorno (POST /arquivos/cnab/retornos) Ler as ocorrências daquele arquivo, daquele dia Planos: Grátis e Personalizado
Listar retornos e obter retorno Recuperar o JSON de um retorno já processado Plano: Personalizado
Consultar situação (GET /boletos/{token}/situacao) Ler o estado consolidado do boleto Plano: Personalizado

Como combinar

Seção intitulada “Como combinar”

Processe o retorno do dia e aplique as ocorrências que o banco informou naquele arquivo. Quando precisar do estado consolidado do boleto, consulte a situação daquele boleto.

Por exemplo, use a ocorrência LIQUIDACAO do retorno para conciliar o pagamento e consulte a situação do boleto quando precisar dos demais dados.

No arquivo de retorno, PROTESTO confirma que o banco recebeu a instrução de protesto; o protesto efetivado chega como BAIXA. Na consulta de situação, leia o bloco protesto.

Veja Também

Seção intitulada “Veja Também”
Consultar situaçãoO estado consolidado do boleto.
Processar retornoEnvie o arquivo de retorno do dia e receba as ocorrências em JSON.
Retorno CNABO que é o arquivo de retorno e quais situações o JSON traz.
Planos & APIO que os planos Grátis e Personalizado cobrem em cada rota.