Implantação Bolecode PIX – Itaú CNAB 400

Nesta Documentação:

O Bolecode PIX é um recurso que permite incluir o código QR PIX nos boletos emitidos pelo Dataplace ERP, possibilitando que os clientes efetuem o pagamento de forma rápida e segura.

Esta documentação apresenta todas as etapas necessárias para configurar o Bolecode PIX, incluindo o cadastro de banco, carteira, credenciamento junto ao banco, geração de certificados digitais e parametrização do QR Code PIX no sistema. Aqui você encontrará instruções detalhadas para realizar cada passo com segurança e eficiência.

Instalação de Softwares Necessários

Para configurar o Bolecode PIX no Dataplace ERP, é necessário instalar dois softwares que permitem executar comandos via API, gerar pares de chaves e certificados digitais: Git Bash e OpenSSL.

Ao Topo

Git Bash

O Git Bash fornece um terminal com comandos do Git e utilitários do Linux, permitindo executar scripts e comandos essenciais para a configuração do Bolecode PIX, inclusive os do OpenSSL.

1. Baixar o Git Bash: Acesse o site oficial do Git: https://git-scm.com/downloads e selecione a versão compatível com o seu sistema operacional. Faça o download do instalador.

2. Executar o Instalador: Execute o instalador baixado e siga as instruções exibidas na tela. É recomendado manter as opções padrão sugeridas, a menos que o ambiente exija alterações.

3. Verificação da instalação: Abra o Git Bash e digite: git –version

  • O sistema exibirá a versão instalada do Git, confirmando que a instalação foi concluída com sucesso.
Ao Topo

OpenSSL

O OpenSSL é utilizado para criar e gerenciar certificados digitais, garantindo que as transações e pagamentos via PIX sejam seguras. Após instalar o Git Bash, os comandos do OpenSSL poderão ser executados diretamente nele.

1. Baixar o OpenSSL: Acesse o site oficial do OpenSSL: https://slproweb.com/products/Win32OpenSSL.html e vá para a seção de downloads. Escolha a versão mais recente compatível com o seu sistema Windows e faça o download do instalador.

2. Executar o Instalador: Execute o instalador baixado e siga as instruções exibidas na tela para concluir a instalação.

3. Configuração de Variáveis de Ambiente (opcional)

  • Adicionar o OpenSSL ao PATH do Windows permite utilizá-lo em qualquer terminal, incluindo o Git Bash:
  • Abra o Painel de Controle e acesse Configurações Avançadas do Sistema.
  • Clique em Variáveis de Ambiente.
  • Na seção Variáveis do Sistema, localize a variável PATH e clique em Editar.
  • Adicione o caminho de instalação do OpenSSL, por exemplo:
  • C:\Program Files\OpenSSL-Win64\bin
  • Clique em OK para salvar as alterações.

4. Verificação da instalação: Abra o Prompt de Comando ou Git Bash e digite: openssl version

  • Se a instalação estiver correta, o sistema exibirá a versão do OpenSSL instalada.

Ao Topo

Solicitar credenciais ao Itaú

Para que o Dataplace ERP possa emitir boletos com QR Code PIX, é necessário obter credenciais junto ao banco Itaú. Essas credenciais permitem que o sistema se autentique com segurança nas APIs do banco e gerencie pagamentos via PIX.

As credenciais incluem:

  • Client ID: identificador da empresa junto ao banco
  • Token provisório: usado para autenticação inicial
  • Chave de sessão: utilizada para criptografar e decifrar informações
  • Client Secret: senha gerada automaticamente pelo banco

Solicitar credenciais ao Itaú

  1. Entre em contato com o gerente ou canal de suporte do Itaú para solicitar o Bolecode.
  2. O banco enviará as credenciais provisórias, como Token temporário e Client ID, e instruções para envio da chave pública.

Ao Topo

Gerar o certificado dinâmico (CSR)

O certificado dinâmico é utilizado para autenticar a comunicação entre o Dataplace ERP e o ambiente do banco Itaú, garantindo a segurança nas operações do Bolecode PIX.
A sigla CSR (Certificate Signing Request) representa um arquivo de solicitação de assinatura de certificado, que contém informações da empresa e é utilizado pelo banco para gerar o certificado digital que autorizará o envio de boletos com QR Code PIX.

Esse processo é essencial para que o ERP possa gerar, assinar e enviar as requisições de cobrança de forma segura.

Ao Topo

Criar Novo Par de Chaves

Para gerar o CSR e a chave privada, abra o Git Bash e execute o seguinte comando:

openssl req -new -subj “//CN={{CLIENT_ID}}\OU={{SITE OU APP DO PARCEIRO}}\L={{CIDADE}}\ST={{ESTADO}}\C={{PAIS}}” -out ARQUIVO_REQUEST_CERTIFICADO.csr -nodes -sha512 -newkey rsa:2048 -keyout ARQUIVO_CHAVE_PRIVADA.key

Legenda dos parâmetros:

  • {{CLIENT_ID}} – Código fornecido pelo banco Itaú.
  • {{SITE OU APP DO PARCEIRO}} – Razão social da empresa.
  • {{CIDADE}} – Cidade da empresa.
  • {{ESTADO}} – UF do endereço da empresa.
  • {{PAIS}} – Normalmente “BR”.

Observação: Todos os campos possuem limite de 50 caracteres e não podem ser utilizados caracteres especiais.

Exemplo prático:

openssl req -new -subj “//CN=56a29ee3-60fe-47f8-95d9-7538b80ccf04\OU=ABC LTDA\L=SAO PAULO\ST=SP\C=BR” -out ARQUIVO_REQUEST_CERTIFICADO.csr -nodes -sha512 -newkey rsa:2048 -keyout ARQUIVO_CHAVE_PRIVADA.key

2. Validar o par de chaves

Após gerar os arquivos, valide as informações executando o comando: openssl req -in ARQUIVO_REQUEST_CERTIFICADO.csr -noout -text

Esse comando exibirá os dados contidos no CSR, permitindo confirmar se as informações foram preenchidas corretamente.

3. Inserir os dados no ERP

Os dados gerados no CSR devem ser informados na aba QR Code PIX da manutenção Carteiras da Conta-Corrente.

Ao Topo

Configurando Banco, Carteira (QRCode PIX)

Essa configuração define as informações necessárias para emissão de boletos com QR Code PIX pelo Itaú, incluindo banco, carteira e parâmetros exigidos para integração via BoleCode. Ela garante que os boletos possam ser pagos tanto por código de barras quanto por QR Code PIX.

Banco >> Configurações

No cadastro de banco, inclua o script de impressão scrImpBloquetoItau04_custom.txt.

Banco >> Carteira >> QR Code PIX

No cadastro da carteira, habilite a utilização do QR Code PIX e preencha os campos solicitados

URLs:

  • Certificado: https://sts.itau.com.br/seguranca/v1/certificado/solicitacao
  • Token: https://sts.itau.com.br/api/oauth/token
  • Location: https://secure.api.itau/pix_recebimentos/v2/loc

Credenciais:

  • Cliente ID: Enviado pelo banco
  • Client Secret: Gerado automaticamente ao clicar em Gerar Certificado dinâmico
  • Token: Enviado pelo banco após geração do Token Temporário. Ou direto caso já decifrado

Certificado Dinâmico CSR:

  • Public Key: conteúdo do arquivo .csr (ARQUIVO_REQUEST_CERTIFICADO.csr)
  • Private Key: conteúdo do arquivo .key (ARQUIVO_CHAVE_PRIVADA.key)
  • Certificado .crt: O sistema gerará as informações e o certificado.crt na pasta Control de forma automática.
    • Isso ocorrerá quando os grupos URL, Credenciais (exceto Client Secret) e Certificado Dinâmico CSR estiverem preenchidos

Ao Topo

Gerar Certificado .pfx

O arquivo .pfx é gerado a partir do arquivo .crt, criado no processo anterior.

Para gerar o arquivo .pfx, execute o seguinte comando no CMD:

openssl pkcs12 -export -out certificado.pfx -inkey ARQUIVO_CHAVE_PRIVADA.key -in ARQUIVO_REQUEST_CERTIFICADO.crt

Os arquivos .crt e .key devem estar no diretório selecionado no Git Bash. Caso não seja possível utilizar o Git Bash, realize o procedimento pelo CMD.

Obs.: Os dígitos da senha não aparecerão, mas estarão sendo registradas normalmente.

Após gerado o certificado .pfx, selecione-o no campo “Path” e insira a senha do mesmo e salve.

Com isso, você concluiu o processo de implantação do BOLECODE PIX do ITAÚ. Se precisar de mais assistência, entre em contato com o suporte técnico, abrindo um chamado no suporte.dataplace.com.br.

Ao Topo

Esta documentação te ajudou?