Baixar ou Cancelar Boleto

Baixar/Cancelar (PUT)

Realiza a baixa (cancelamento) do boleto, removendo-o da cobrança ativa. Uma vez baixado, o boleto não pode ser pago pelo pagador na rede bancária.

O que Acontece na Baixa

1. O status do boleto no Boleto Cloud muda para “Baixado da Cobrança”
2. A instrução de baixa é enviada ao banco conforme o tipo de comunicação da conta

Comportamento por Tipo de Comunicação

Tipo de Comunicação	O que acontece
API/Webservice (automático)	Baixa enviada automaticamente ao banco
Arquivo CNAB (manual)	Instrução de baixa incluída no próximo arquivo de remessa para importação manual no banco

Nota

Se sua conta bancária opera com arquivo de remessa manual, a baixa só será efetivada no banco após você gerar o arquivo de remessa (com a instrução de baixa) e importá-lo no sistema do banco.

Quando Usar

Cenário	Recomendação
Cliente pagou por outro meio (Pix, transferência, dinheiro)	Sim
Cancelamento de venda ou contrato	Sim
Boleto emitido por engano	Sim
Substituição por novo boleto	Sim
Renegociação de dívida com novo boleto	Sim

Endpoint

PUT https://sandbox.boletocloud.com/api/v1/boletos/{token_do_boleto}/baixa

Headers

Header	Valor
Content-Type	application/json; charset=utf-8
Authorization	Basic {credenciais}

Body da Requisição

O corpo da requisição deve conter o motivo da baixa em formato JSON.

Com motivo definido:

{
  "boleto": {
    "baixa": {
      "motivo": "Cancelamento do plano"
    }
  }
}

Sem motivo definido:

{
  "boleto": {
    "baixa": {
      "motivo": null
    }
  }
}

Nota

Mesmo que não exista um motivo para a baixa, o campo motivo deve ser enviado com valor null.

Códigos de Resposta

Código	Descrição
201 Created	Baixa realizada com sucesso
409 Conflict	Boleto já foi baixado anteriormente

Exemplos de Código

cURL

curl -v "https://sandbox.boletocloud.com/api/v1/boletos/{token_do_boleto}/baixa" \
  -H "Content-Type: application/json; charset=utf-8" \
  -X "PUT" \
  -u "api-key_SUA-API-KEY:token" \
  -d '{"boleto":{"baixa":{"motivo":"Cancelamento do plano"}}}'

Java

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;
import static javax.ws.rs.core.MediaType.APPLICATION_JSON;

public class BaixaBoleto {
    public static void main(String[] args) {
        String tokenBoleto = "TOKEN_DO_BOLETO";
        String json = "{\"boleto\":{\"baixa\":{\"motivo\":\"Cancelamento do plano\"}}}";

        Response response = ClientBuilder.newClient()
            .target("https://sandbox.boletocloud.com/api/v1/boletos")
            .path("/" + tokenBoleto + "/baixa")
            .register(HttpAuthenticationFeature.basic("api-key_SUA-API-KEY", "token"))
            .request(APPLICATION_JSON)
            .put(Entity.json(json));

        if (response.getStatus() == 201) {
            System.out.println("Boleto baixado com sucesso!");
        } else if (response.getStatus() == 409) {
            System.out.println("Erro: Boleto já foi baixado anteriormente.");
        } else {
            System.out.println("Erro: " + response.readEntity(String.class));
        }
    }
}

Kotlin

import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

fun main() {
    val tokenBoleto = "TOKEN_DO_BOLETO"
    val client = OkHttpClient()
    val credential = Credentials.basic("api-key_SUA-API-KEY", "token")
    val json = """{"boleto":{"baixa":{"motivo":"Cancelamento do plano"}}}"""

    val request = Request.Builder()
        .url("https://sandbox.boletocloud.com/api/v1/boletos/$tokenBoleto/baixa")
        .header("Authorization", credential)
        .put(json.toRequestBody("application/json".toMediaType()))
        .build()

    client.newCall(request).execute().use { response ->
        when (response.code) {
            201 -> println("Boleto baixado com sucesso!")
            409 -> println("Erro: Boleto já foi baixado anteriormente.")
            else -> println("Erro: ${response.code}")
        }
    }
}

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        var tokenBoleto = "TOKEN_DO_BOLETO";
        using var client = new HttpClient();
        var credentials = Convert.ToBase64String(
            Encoding.ASCII.GetBytes("api-key_SUA-API-KEY:token"));
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Basic", credentials);

        var json = "{\"boleto\":{\"baixa\":{\"motivo\":\"Cancelamento do plano\"}}}";
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        var response = await client.PutAsync(
            $"https://sandbox.boletocloud.com/api/v1/boletos/{tokenBoleto}/baixa", content);

        var status = (int)response.StatusCode;
        if (status == 201) Console.WriteLine("Boleto baixado com sucesso!");
        else if (status == 409) Console.WriteLine("Erro: Boleto já foi baixado anteriormente.");
        else Console.WriteLine($"Erro: {status}");
    }
}

Node

const https = require('https');

const tokenBoleto = 'TOKEN_DO_BOLETO';
const data = JSON.stringify({boleto: {baixa: {motivo: 'Cancelamento do plano'}}});

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: `/api/v1/boletos/${tokenBoleto}/baixa`,
  method: 'PUT',
  auth: 'api-key_SUA-API-KEY:token',
  headers: {'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data)}
};

const req = https.request(options, (res) => {
  if (res.statusCode === 201) console.log('Boleto baixado com sucesso!');
  else if (res.statusCode === 409) console.log('Erro: Boleto já foi baixado anteriormente.');
  else console.log(`Erro: ${res.statusCode}`);
});

req.write(data);
req.end();

Go

package main

import (
    "fmt"
    "net/http"
    "strings"
)

func main() {
    tokenBoleto := "TOKEN_DO_BOLETO"
    json := `{"boleto":{"baixa":{"motivo":"Cancelamento do plano"}}}`
    url := "https://sandbox.boletocloud.com/api/v1/boletos/" + tokenBoleto + "/baixa"

    req, _ := http.NewRequest("PUT", url, strings.NewReader(json))
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    switch resp.StatusCode {
    case 201: fmt.Println("Boleto baixado com sucesso!")
    case 409: fmt.Println("Erro: Boleto já foi baixado anteriormente.")
    default: fmt.Printf("Erro: %d\n", resp.StatusCode)
    }
}

PHP

<?php
$tokenBoleto = 'TOKEN_DO_BOLETO';
$url = "https://sandbox.boletocloud.com/api/v1/boletos/$tokenBoleto/baixa";
$api_key = 'api-key_SUA-API-KEY';
$data = json_encode(['boleto' => ['baixa' => ['motivo' => 'Cancelamento do plano']]]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$api_key:token");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code == 201) echo "Boleto baixado com sucesso!\n";
else if ($http_code == 409) echo "Erro: Boleto já foi baixado anteriormente.\n";
else echo "Erro: $response\n";
?>

Python

import requests
from requests.auth import HTTPBasicAuth

token_boleto = 'TOKEN_DO_BOLETO'
response = requests.put(
    f'https://sandbox.boletocloud.com/api/v1/boletos/{token_boleto}/baixa',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    json={'boleto': {'baixa': {'motivo': 'Cancelamento do plano'}}}
)

if response.status_code == 201:
    print('Boleto baixado com sucesso!')
elif response.status_code == 409:
    print('Erro: Boleto já foi baixado anteriormente.')
else:
    print(f'Erro: {response.status_code}')

Ruby

require 'net/http'
require 'uri'
require 'json'

token_boleto = 'TOKEN_DO_BOLETO'
uri = URI("https://sandbox.boletocloud.com/api/v1/boletos/#{token_boleto}/baixa")

Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  request = Net::HTTP::Put.new(uri)
  request.basic_auth('api-key_SUA-API-KEY', 'token')
  request['Content-Type'] = 'application/json'
  request.body = {boleto: {baixa: {motivo: 'Cancelamento do plano'}}}.to_json

  response = http.request(request)
  case response.code
  when '201' then puts 'Boleto baixado com sucesso!'
  when '409' then puts 'Erro: Boleto já foi baixado anteriormente.'
  else puts "Erro: #{response.code}"
  end
end

Clojure

(require '[clj-http.client :as client])

(let [token-boleto "TOKEN_DO_BOLETO"
      response (client/put
                (str "https://sandbox.boletocloud.com/api/v1/boletos/" token-boleto "/baixa")
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :content-type :json
                 :body "{\"boleto\":{\"baixa\":{\"motivo\":\"Cancelamento do plano\"}}}"
                 :throw-exceptions false})]
  (case (:status response)
    201 (println "Boleto baixado com sucesso!")
    409 (println "Erro: Boleto já foi baixado anteriormente.")
    (println "Erro:" (:status response))))

Cuidado

A baixa é uma operação irreversível. Uma vez cancelado, o boleto não pode ser reativado. Certifique-se de que deseja realmente cancelar o boleto antes de realizar a operação.

Veja Também

Obter PDF Original Recuperar o PDF do boleto

Status do Registro Verificar se o boleto foi registrado

Arquivo de Remessa Integração via arquivo CNAB

Arquivo de Retorno Processar confirmações do banco