Pular para o conteúdo

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.


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

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.

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

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 Pix Suportado
API bancária (automático) Sim — QR Code no PDF imediatamente
Arquivo CNAB (manual) Depende do banco e layout CNAB

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.

Terminal window
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)

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"
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