Boleto com Pix

O boleto híbrido (BolePix) combina código de barras + QR Code Pix em um único documento. O pagador escolhe: pagar em D+1 pelo código de barras ou instantaneamente pelo Pix, 24/7.

Boleto híbrido com QR Code Pix e código de barras

Na API Boleto Cloud, a requisição para criar um boleto com Pix é idêntica à de um boleto comum — nenhum campo adicional é necessário. O Pix é habilitado na configuração da conta bancária na plataforma.

Pré-requisitos

Para que o boleto saia com QR Code Pix, a conta bancária precisa estar preparada:

Chave Pix habilitada no banco — vinculada à mesma conta que emite os boletos
Conta configurada no Boleto Cloud para Pix — habilitação feita pelo suporte
Homologação concluída — validação de que o boleto com Pix está sendo gerado corretamente

Como gerar

Use o mesmo endpoint POST /boletos e os mesmos campos da criação de boleto. Se a conta bancária estiver configurada para Pix, o boleto já será gerado com o QR Code automaticamente.

Resposta

Na resposta 201, o PDF já vem com o QR Code Pix. Além dos headers padrão, o plano personalizado retorna um header adicional:

Header	Descrição
`X-BoletoCloud-Pix-Codigo-EMV`	Código Pix copia-e-cola (EMV) — pode ser usado diretamente no app do banco, sem escanear o QR Code

Configuração da chave Pix no banco

O Boleto Cloud abstrai a complexidade de cada banco. Você não precisa se preocupar com como a chave Pix é tratada internamente — basta que ela esteja configurada corretamente no banco.

Banco	Chave recomendada	Como configurar
Banco do Brasil	Qualquer chave da conta	Vinculada à conta corrente
Bradesco	Aleatória (EVP)	Configurada na carteira de cobrança
Itaú	Qualquer chave da conta	Suporta chave específica por boleto
Santander	CPF, CNPJ, celular, e-mail ou EVP	Configurada na conta
Sicoob	Aleatória (EVP)	Habilitada pela cooperativa (veja abaixo)
Caixa	Vinculada pelo gerente	Contratar “Cobrança Bancária Híbrida”
Inter	Aleatória (EVP)	API V3 já inclui Pix por padrão
Sicredi	Vinculada à conta	Habilitada no cadastro da conta

Via de registro e Pix

Via de Registro	Pix Suportado
API bancária (automático)	Sim — QR Code no PDF imediatamente
Arquivo CNAB (manual)	Depende do banco e layout CNAB

Exemplos de Código

A requisição é idêntica à criação de boleto padrão. Os exemplos abaixo mostram como capturar o header X-BoletoCloud-Pix-Codigo-EMV na resposta.

curl -v "https://sandbox.boletocloud.com/api/v1/boletos" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -X "POST" \
  -u "api-key_SUA-API-KEY:token" \
  -d boleto.conta.token="api-key_SEU-TOKEN-DA-CONTA" \
  -d boleto.emissao="2024-01-15" \
  -d boleto.vencimento="2024-02-15" \
  -d boleto.documento="PIX-001" \
  -d boleto.titulo="DM" \
  -d boleto.valor="199.90" \
  -d boleto.pagador.nome="Ana Paula" \
  -d boleto.pagador.cprf="000.000.000-00" \
  -d boleto.pagador.endereco.cep="00000-000" \
  -d boleto.pagador.endereco.uf="PR" \
  -d boleto.pagador.endereco.localidade="Curitiba" \
  -d boleto.pagador.endereco.bairro="Batel" \
  -d boleto.pagador.endereco.logradouro="Av. Batel" \
  -d boleto.pagador.endereco.numero="1500" \
  -o boleto-pix.pdf

# Se a conta estiver habilitada para Pix, o PDF já vem com QR Code.
# Use -v ou -D headers.txt para capturar:
# X-BoletoCloud-Token → token do boleto
# X-BoletoCloud-Pix-Codigo-EMV → código Pix copia-e-cola (plano personalizado)

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Form;
import javax.ws.rs.core.Response;
import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;

public class CriarBoletoPix {
    public static void main(String[] args) throws Exception {
        Form form = new Form()
            .param("boleto.conta.token", "api-key_SEU-TOKEN-DA-CONTA")
            .param("boleto.emissao", "2024-01-15")
            .param("boleto.vencimento", "2024-02-15")
            .param("boleto.documento", "PIX-001")
            .param("boleto.titulo", "DM")
            .param("boleto.valor", "199.90")
            .param("boleto.pagador.nome", "Ana Paula")
            .param("boleto.pagador.cprf", "000.000.000-00")
            .param("boleto.pagador.endereco.cep", "00000-000")
            .param("boleto.pagador.endereco.uf", "PR")
            .param("boleto.pagador.endereco.localidade", "Curitiba")
            .param("boleto.pagador.endereco.bairro", "Batel")
            .param("boleto.pagador.endereco.logradouro", "Av. Batel")
            .param("boleto.pagador.endereco.numero", "1500");

        Response response = ClientBuilder.newClient()
            .target("https://sandbox.boletocloud.com/api/v1/boletos")
            .register(HttpAuthenticationFeature.basic("api-key_SUA-API-KEY", "token"))
            .request()
            .post(Entity.form(form));

        switch (response.getStatus()) {
            case 201:
                String token = response.getHeaderString("X-BoletoCloud-Token");
                String pixEmv = response.getHeaderString("X-BoletoCloud-Pix-Codigo-EMV");
                System.out.println("Boleto criado! Token: " + token);
                if (pixEmv != null) {
                    System.out.println("Pix Copia-e-Cola: " + pixEmv);
                }
                Files.copy(response.readEntity(InputStream.class),
                    Paths.get("boleto-pix.pdf"), REPLACE_EXISTING);
                break;
            case 409:
                System.out.println("Boleto já existe. Token: "
                    + response.getHeaderString("X-BoletoCloud-Token"));
                break;
            default:
                System.out.println("Erro: " + response.readEntity(String.class));
        }
    }
}

import okhttp3.*
import java.io.File

fun main() {
    val client = OkHttpClient()
    val credential = Credentials.basic("api-key_SUA-API-KEY", "token")

    val body = FormBody.Builder()
        .add("boleto.conta.token", "api-key_SEU-TOKEN-DA-CONTA")
        .add("boleto.emissao", "2024-01-15")
        .add("boleto.vencimento", "2024-02-15")
        .add("boleto.documento", "PIX-001")
        .add("boleto.titulo", "DM")
        .add("boleto.valor", "199.90")
        .add("boleto.pagador.nome", "Ana Paula")
        .add("boleto.pagador.cprf", "000.000.000-00")
        .add("boleto.pagador.endereco.cep", "00000-000")
        .add("boleto.pagador.endereco.uf", "PR")
        .add("boleto.pagador.endereco.localidade", "Curitiba")
        .add("boleto.pagador.endereco.bairro", "Batel")
        .add("boleto.pagador.endereco.logradouro", "Av. Batel")
        .add("boleto.pagador.endereco.numero", "1500")
        .build()

    val request = Request.Builder()
        .url("https://sandbox.boletocloud.com/api/v1/boletos")
        .header("Authorization", credential)
        .post(body)
        .build()

    client.newCall(request).execute().use { response ->
        when (response.code) {
            201 -> {
                val token = response.header("X-BoletoCloud-Token")
                val pixEmv = response.header("X-BoletoCloud-Pix-Codigo-EMV")
                println("Boleto criado! Token: $token")
                pixEmv?.let { println("Pix Copia-e-Cola: $it") }
                File("boleto-pix.pdf").writeBytes(response.body!!.bytes())
            }
            409 -> println("Boleto já existe. Token: ${response.header("X-BoletoCloud-Token")}")
            else -> println("Erro: ${response.body?.string()}")
        }
    }
}

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        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 content = new FormUrlEncodedContent(new Dictionary<string, string> {
            {"boleto.conta.token", "api-key_SEU-TOKEN-DA-CONTA"},
            {"boleto.emissao", "2024-01-15"},
            {"boleto.vencimento", "2024-02-15"},
            {"boleto.documento", "PIX-001"},
            {"boleto.titulo", "DM"},
            {"boleto.valor", "199.90"},
            {"boleto.pagador.nome", "Ana Paula"},
            {"boleto.pagador.cprf", "000.000.000-00"},
            {"boleto.pagador.endereco.cep", "00000-000"},
            {"boleto.pagador.endereco.uf", "PR"},
            {"boleto.pagador.endereco.localidade", "Curitiba"},
            {"boleto.pagador.endereco.bairro", "Batel"},
            {"boleto.pagador.endereco.logradouro", "Av. Batel"},
            {"boleto.pagador.endereco.numero", "1500"}
        });

        var response = await client.PostAsync(
            "https://sandbox.boletocloud.com/api/v1/boletos", content);
        var statusCode = (int)response.StatusCode;

        switch (statusCode) {
            case 201:
                var token = response.Headers.GetValues("X-BoletoCloud-Token").First();
                Console.WriteLine($"Boleto criado! Token: {token}");
                if (response.Headers.Contains("X-BoletoCloud-Pix-Codigo-EMV")) {
                    var pixEmv = response.Headers
                        .GetValues("X-BoletoCloud-Pix-Codigo-EMV").First();
                    Console.WriteLine($"Pix Copia-e-Cola: {pixEmv}");
                }
                var pdf = await response.Content.ReadAsByteArrayAsync();
                await File.WriteAllBytesAsync("boleto-pix.pdf", pdf);
                break;
            case 409:
                var tokenExistente = response.Headers
                    .GetValues("X-BoletoCloud-Token").First();
                Console.WriteLine($"Boleto já existe. Token: {tokenExistente}");
                break;
            default:
                var erro = await response.Content.ReadAsStringAsync();
                Console.WriteLine($"Erro: {erro}");
                break;
        }
    }
}

const https = require('https');
const fs = require('fs');
const querystring = require('querystring');

const data = querystring.stringify({
  'boleto.conta.token': 'api-key_SEU-TOKEN-DA-CONTA',
  'boleto.emissao': '2024-01-15',
  'boleto.vencimento': '2024-02-15',
  'boleto.documento': 'PIX-001',
  'boleto.titulo': 'DM',
  'boleto.valor': '199.90',
  'boleto.pagador.nome': 'Ana Paula',
  'boleto.pagador.cprf': '000.000.000-00',
  'boleto.pagador.endereco.cep': '00000-000',
  'boleto.pagador.endereco.uf': 'PR',
  'boleto.pagador.endereco.localidade': 'Curitiba',
  'boleto.pagador.endereco.bairro': 'Batel',
  'boleto.pagador.endereco.logradouro': 'Av. Batel',
  'boleto.pagador.endereco.numero': '1500'
});

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: '/api/v1/boletos',
  method: 'POST',
  auth: 'api-key_SUA-API-KEY:token',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request(options, (res) => {
  const token = res.headers['x-boletocloud-token'];
  const pixEmv = res.headers['x-boletocloud-pix-codigo-emv'];

  switch (res.statusCode) {
    case 201:
      console.log('Boleto criado! Token:', token);
      if (pixEmv) console.log('Pix Copia-e-Cola:', pixEmv);
      const file = fs.createWriteStream('boleto-pix.pdf');
      res.pipe(file);
      break;
    case 409:
      console.log('Boleto já existe. Token:', token);
      break;
    default:
      let body = '';
      res.on('data', chunk => body += chunk);
      res.on('end', () => console.log('Erro:', body));
  }
});

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

package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strings"
)

func main() {
    data := url.Values{
        "boleto.conta.token":                 {"api-key_SEU-TOKEN-DA-CONTA"},
        "boleto.emissao":                     {"2024-01-15"},
        "boleto.vencimento":                  {"2024-02-15"},
        "boleto.documento":                   {"PIX-001"},
        "boleto.titulo":                      {"DM"},
        "boleto.valor":                       {"199.90"},
        "boleto.pagador.nome":                {"Ana Paula"},
        "boleto.pagador.cprf":                {"000.000.000-00"},
        "boleto.pagador.endereco.cep":        {"00000-000"},
        "boleto.pagador.endereco.uf":         {"PR"},
        "boleto.pagador.endereco.localidade": {"Curitiba"},
        "boleto.pagador.endereco.bairro":     {"Batel"},
        "boleto.pagador.endereco.logradouro": {"Av. Batel"},
        "boleto.pagador.endereco.numero":     {"1500"},
    }

    req, _ := http.NewRequest("POST",
        "https://sandbox.boletocloud.com/api/v1/boletos",
        strings.NewReader(data.Encode()))
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

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

    token := resp.Header.Get("X-BoletoCloud-Token")
    pixEmv := resp.Header.Get("X-BoletoCloud-Pix-Codigo-EMV")

    switch resp.StatusCode {
    case 201:
        fmt.Println("Boleto criado! Token:", token)
        if pixEmv != "" {
            fmt.Println("Pix Copia-e-Cola:", pixEmv)
        }
        file, _ := os.Create("boleto-pix.pdf")
        defer file.Close()
        io.Copy(file, resp.Body)
    case 409:
        fmt.Println("Boleto já existe. Token:", token)
    default:
        body, _ := io.ReadAll(resp.Body)
        fmt.Println("Erro:", string(body))
    }
}

<?php
$url = 'https://sandbox.boletocloud.com/api/v1/boletos';
$api_key = 'api-key_SUA-API-KEY';

$data = http_build_query([
    'boleto.conta.token' => 'api-key_SEU-TOKEN-DA-CONTA',
    'boleto.emissao' => '2024-01-15',
    'boleto.vencimento' => '2024-02-15',
    'boleto.documento' => 'PIX-001',
    'boleto.titulo' => 'DM',
    'boleto.valor' => '199.90',
    'boleto.pagador.nome' => 'Ana Paula',
    'boleto.pagador.cprf' => '000.000.000-00',
    'boleto.pagador.endereco.cep' => '00000-000',
    'boleto.pagador.endereco.uf' => 'PR',
    'boleto.pagador.endereco.localidade' => 'Curitiba',
    'boleto.pagador.endereco.bairro' => 'Batel',
    'boleto.pagador.endereco.logradouro' => 'Av. Batel',
    'boleto.pagador.endereco.numero' => '1500'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$api_key:token");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, true);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers = substr($response, 0, $header_size);
$body = substr($response, $header_size);
curl_close($ch);

preg_match('/X-BoletoCloud-Token:\s*(.+)/i', $headers, $tokenMatch);
preg_match('/X-BoletoCloud-Pix-Codigo-EMV:\s*(.+)/i', $headers, $pixMatch);
$token = trim($tokenMatch[1] ?? '');
$pixEmv = trim($pixMatch[1] ?? '');

switch ($http_code) {
    case 201:
        echo "Boleto criado! Token: $token\n";
        if ($pixEmv) echo "Pix Copia-e-Cola: $pixEmv\n";
        file_put_contents('boleto-pix.pdf', $body);
        break;
    case 409:
        echo "Boleto já existe. Token: $token\n";
        break;
    default:
        echo "Erro ($http_code): $body\n";
}
?>

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    'https://sandbox.boletocloud.com/api/v1/boletos',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    data={
        'boleto.conta.token': 'api-key_SEU-TOKEN-DA-CONTA',
        'boleto.emissao': '2024-01-15',
        'boleto.vencimento': '2024-02-15',
        'boleto.documento': 'PIX-001',
        'boleto.titulo': 'DM',
        'boleto.valor': '199.90',
        'boleto.pagador.nome': 'Ana Paula',
        'boleto.pagador.cprf': '000.000.000-00',
        'boleto.pagador.endereco.cep': '00000-000',
        'boleto.pagador.endereco.uf': 'PR',
        'boleto.pagador.endereco.localidade': 'Curitiba',
        'boleto.pagador.endereco.bairro': 'Batel',
        'boleto.pagador.endereco.logradouro': 'Av. Batel',
        'boleto.pagador.endereco.numero': '1500'
    }
)

token = response.headers.get('X-BoletoCloud-Token')
pix_emv = response.headers.get('X-BoletoCloud-Pix-Codigo-EMV')

if response.status_code == 201:
    print(f'Boleto criado! Token: {token}')
    if pix_emv:
        print(f'Pix Copia-e-Cola: {pix_emv}')
    with open('boleto-pix.pdf', 'wb') as f:
        f.write(response.content)
elif response.status_code == 409:
    print(f'Boleto já existe. Token: {token}')
else:
    print(f'Erro: {response.text}')

require 'net/http'
require 'uri'

uri = URI('https://sandbox.boletocloud.com/api/v1/boletos')

Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  request = Net::HTTP::Post.new(uri)
  request.basic_auth('api-key_SUA-API-KEY', 'token')
  request.set_form_data(
    'boleto.conta.token' => 'api-key_SEU-TOKEN-DA-CONTA',
    'boleto.emissao' => '2024-01-15',
    'boleto.vencimento' => '2024-02-15',
    'boleto.documento' => 'PIX-001',
    'boleto.titulo' => 'DM',
    'boleto.valor' => '199.90',
    'boleto.pagador.nome' => 'Ana Paula',
    'boleto.pagador.cprf' => '000.000.000-00',
    'boleto.pagador.endereco.cep' => '00000-000',
    'boleto.pagador.endereco.uf' => 'PR',
    'boleto.pagador.endereco.localidade' => 'Curitiba',
    'boleto.pagador.endereco.bairro' => 'Batel',
    'boleto.pagador.endereco.logradouro' => 'Av. Batel',
    'boleto.pagador.endereco.numero' => '1500'
  )

  response = http.request(request)
  token = response['X-BoletoCloud-Token']
  pix_emv = response['X-BoletoCloud-Pix-Codigo-EMV']

  case response.code
  when '201'
    puts "Boleto criado! Token: #{token}"
    puts "Pix Copia-e-Cola: #{pix_emv}" if pix_emv
    File.write('boleto-pix.pdf', response.body)
  when '409'
    puts "Boleto já existe. Token: #{token}"
  else
    puts "Erro: #{response.body}"
  end
end

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

(let [response (client/post
                "https://sandbox.boletocloud.com/api/v1/boletos"
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :form-params {:boleto.conta.token "api-key_SEU-TOKEN-DA-CONTA"
                               :boleto.emissao "2024-01-15"
                               :boleto.vencimento "2024-02-15"
                               :boleto.documento "PIX-001"
                               :boleto.titulo "DM"
                               :boleto.valor "199.90"
                               :boleto.pagador.nome "Ana Paula"
                               :boleto.pagador.cprf "000.000.000-00"
                               :boleto.pagador.endereco.cep "00000-000"
                               :boleto.pagador.endereco.uf "PR"
                               :boleto.pagador.endereco.localidade "Curitiba"
                               :boleto.pagador.endereco.bairro "Batel"
                               :boleto.pagador.endereco.logradouro "Av. Batel"
                               :boleto.pagador.endereco.numero "1500"}
                 :as :byte-array
                 :throw-exceptions false})
      token (get-in response [:headers "X-BoletoCloud-Token"])
      pix-emv (get-in response [:headers "X-BoletoCloud-Pix-Codigo-EMV"])]
  (case (:status response)
    201 (do
          (println "Boleto criado! Token:" token)
          (when pix-emv (println "Pix Copia-e-Cola:" pix-emv))
          (clojure.java.io/copy (:body response)
            (clojure.java.io/file "boleto-pix.pdf")))
    409 (println "Boleto já existe. Token:" token)
    (println "Erro:" (String. (:body response)))))

Importar QR Code Pix de outro sistema

Se o boleto já foi criado com Pix em outro sistema e você quer importá-lo para o Boleto Cloud mantendo o QR Code original, envie os campos boleto.pix.txid e boleto.pix.url junto com os dados do boleto:

Campo	Tipo	Tamanho	Exemplo
`boleto.pix.txid`	string	35 caracteres (exato)	`"20220725237092656003585100000118803"`
`boleto.pix.url`	string	67-77 caracteres	`"qrcodepix.bb.com.br/pix/v2/cobv/09e1e779-f64b-4b2c-989c-9eab7ead3c10"`

Exemplo de body com importação Pix

boleto.conta.token=api-key_SEU-TOKEN-DA-CONTA
boleto.emissao=2024-01-15
boleto.vencimento=2024-02-15
boleto.documento=IMP-001
boleto.titulo=DM
boleto.valor=350.00
boleto.numero=00000012345-6
boleto.pix.txid=20220725237092656003585100000118803
boleto.pix.url=qrcodepix.bb.com.br/pix/v2/cobv/09e1e779-f64b-4b2c-989c-9eab7ead3c10
boleto.pagador.nome=Alberto Santos Dumont
boleto.pagador.cprf=111.111.111-11
boleto.pagador.endereco.cep=36240-000
boleto.pagador.endereco.uf=MG
boleto.pagador.endereco.localidade=Santos Dumont
boleto.pagador.endereco.bairro=Centro
boleto.pagador.endereco.logradouro=Rua Principal
boleto.pagador.endereco.numero=123

Veja Também

Criar Boleto Referência completa com todos os campos e respostas

Campos do Boleto Todos os campos, incluindo Pix de importação

Bancos Suportados Bancos disponíveis para boleto com Pix

Suporte Homologar Pix na sua conta bancária

Anterior
Listar Retornos (GET) Próximo
Registrar Boleto Depois