Alterar Valor do Boleto

Plano: Personalizado

Altera o valor do boleto no Boleto Cloud. A alteração não é enviada ao banco: ela muda o valor na plataforma enquanto o registro do boleto não estiver confirmado. Depois da alteração, obtenha o PDF de novo com Obter PDF original (GET /boletos/{token}).

Recurso do plano Personalizado

Sem o plano Personalizado ativo, esta rota responde 403 com o código 8D1C5814. Isso vale também no sandbox: ao contratar o plano, ele é ativado nas contas de produção e de sandbox.

Veja o que cada plano inclui

O que este endpoint faz

1. Recebe o novo valor do boleto em JSON.
2. Atualiza esse valor no Boleto Cloud enquanto o registro não estiver confirmado.
3. Não envia a alteração ao banco.
4. Responde 200 sem corpo quando a alteração é aceita.

Quando usar

Use este endpoint para corrigir o valor do boleto no Boleto Cloud antes de o banco confirmar o registro. Se o registro já foi confirmado, baixe o boleto e emita um novo.

Cenários recomendados

Cenário	Recomendação
Corrigir o valor antes de enviar o boleto para registro	Sim
O banco já confirmou o registro	Não. Baixe o boleto e emita um novo

Onde se encaixa no ciclo de vida

O boleto já foi emitido e o registro ainda não foi confirmado pelo banco; depois da alteração, obtenha o PDF de novo em Obter PDF original, e, se o banco já confirmou o registro, baixe o boleto e emita um novo.

Pré-requisitos

• O boleto já existe e você tem o token_do_boleto.
• O registro ainda não foi confirmado pelo banco. Nesse estado, a alteração vale para qualquer banco.

A autenticação é HTTP Basic com a API Key. Veja Autenticação.

Endpoint

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

Sandbox Desenvolvimento e testes

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

Produção Operação real

https://app.boletocloud.com/api/v1/boletos/{token_do_boleto}/valor

A rota é a mesma nos dois ambientes; só o host muda. Em Produção, use a API Key e o token da conta de Produção.

Atenção

Enquanto sua aplicação estiver em desenvolvimento, use somente o endpoint Sandbox, em https://sandbox.boletocloud.com. Isso evita problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma. Quando os testes terminarem, siga o roteiro Do Sandbox para a Produção.

Requisição

Headers

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

Parâmetros da URL

Parâmetro	Obrigatório	Descrição
token_do_boleto	Sim	Token do boleto

Body (application/json)

O corpo da requisição traz o novo valor em JSON.

Campos obrigatórios

Campo	Tipo	Exemplo	Descrição
boleto.valor	decimal	150.00	Novo valor do boleto

Validações

Formato do valor

boleto.valor é um decimal de 0.00 a 99999999.99, com até 8 dígitos inteiros e 2 decimais.

Exemplo de body

{
  "boleto": {
    "valor": 150.00
  }
}

Exemplos de código

cURL

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

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 AlterarValor {
    public static void main(String[] args) {
        String tokenBoleto = "TOKEN_DO_BOLETO";
        String json = "{\"boleto\":{\"valor\":150.00}}";

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

        if (response.getStatus() == 200) {
            System.out.println("Valor alterado com sucesso!");
        } else {
            System.out.println("Erro: " + response.getStatus());
        }
    }
}

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":{"valor":150.00}}"""

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

    client.newCall(request).execute().use { response ->
        if (response.code == 200) println("Valor alterado com sucesso!")
        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\":{\"valor\":150.00}}";
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        var response = await client.PutAsync(
            $"https://sandbox.boletocloud.com/api/v1/boletos/{tokenBoleto}/valor", content);

        if ((int)response.StatusCode == 200)
            Console.WriteLine("Valor alterado com sucesso!");
        else
            Console.WriteLine($"Erro: {(int)response.StatusCode}");
    }
}

Node

const https = require('https');

const tokenBoleto = 'TOKEN_DO_BOLETO';
const data = '{"boleto":{"valor":150.00}}';

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: `/api/v1/boletos/${tokenBoleto}/valor`,
  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 === 200) console.log('Valor alterado com sucesso!');
  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":{"valor":150.00}}`
    url := "https://sandbox.boletocloud.com/api/v1/boletos/" + tokenBoleto + "/valor"

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

    if resp.StatusCode == 200 {
        fmt.Println("Valor alterado com sucesso!")
    } else {
        fmt.Printf("Erro: %d\n", resp.StatusCode)
    }
}

PHP

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

$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 == 200) echo "Valor alterado com sucesso!\n";
else echo "Erro ($http_code): $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}/valor',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    json={'boleto': {'valor': 150.00}}
)

if response.status_code == 200:
    print('Valor alterado com sucesso!')
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}/valor")

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: {valor: 150.00}}.to_json

  response = http.request(request)
  if response.code == '200'
    puts 'Valor alterado com sucesso!'
  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 "/valor")
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :content-type :json
                 :body "{\"boleto\":{\"valor\":150.00}}"
                 :throw-exceptions false})]
  (if (= 200 (:status response))
    (println "Valor alterado com sucesso!")
    (println "Erro:" (:status response))))

Resposta

200 OK — Valor alterado

O valor foi alterado. A resposta não tem corpo e traz o header X-BoletoCloud-Version.

Headers

Header	Descrição
X-BoletoCloud-Version	Versão da plataforma

Body

Sem corpo.

Como interpretar

O 200 confirma que o valor mudou no Boleto Cloud. Obtenha o PDF de novo em Obter PDF original (GET /boletos/{token}) para ter o boleto com o novo valor.

Erros

No 400, o tipo é requisicao.

Status	Código	Quando ocorre	O que fazer
400	96660E9E	Token do boleto inválido ou inexistente.	Verifique o token do boleto.
400	3E0817D2	Valor ausente.	Informe boleto.valor.
400	638E2C96	Valor abaixo do mínimo 0.00.	Envie um valor de 0.00 a 99999999.99.
400	EDBFA093	Valor acima do máximo 99999999.99.	Envie um valor até 99999999.99.
400	DB2DC467	Dígitos fora do formato: até 8 inteiros e 2 decimais.	Ajuste o valor para até 8 inteiros e 2 decimais.
400	97E0D35F	Registro já confirmado pelo banco.	Baixe o boleto e emita um novo.
403	8D1C5814	Sem o plano Personalizado.	Veja Planos & API.

A lista completa dos códigos está em Códigos de erro.

400 Bad Request — Registro já confirmado

Registro já confirmado

A alteração funciona para qualquer banco enquanto o registro do boleto não estiver confirmado. Depois que o banco confirma o registro, a API responde 400, com tipo requisicao e código 97E0D35F. A mensagem é Boleto com token (TOKEN_DO_BOLETO) já registrado. Não pode ter valor alterado sem gerar remessa de alteração. Para um boleto já registrado, baixe o boleto e emita um novo.

Body

{
  "erro": {
    "status": 400,
    "tipo": "requisicao",
    "causas": [
      {
        "codigo": "97E0D35F",
        "mensagem": "Boleto com token (TOKEN_DO_BOLETO) já registrado. Não pode ter valor alterado sem gerar remessa de alteração.",
        "suporte": "https://developers.boleto.cloud"
      }
    ]
  }
}

Comunicação com o banco

A alteração não é enviada ao banco. Ela muda o valor no Boleto Cloud. Altere o valor antes de enviar o boleto para registro. Se a remessa já foi enviada e o registro ainda não foi confirmado, o banco registra o valor que recebeu.

Próximos passos

• Obtenha o PDF de novo em Obter PDF original (GET /boletos/{token}).
• Se o banco já confirmou o registro, baixe o boleto e emita um novo.

Veja Também

Alterar vencimentoAlterar a data de vencimento do boleto

Baixar boletoCancelar a cobrança quando o registro já foi confirmado

Obter PDF originalBaixar de novo o PDF com o valor alterado

Códigos de erroCatálogo dos códigos de erro da API