Guia de Integração | Itaú PIX e Bolecode

---

1. Introdução

A integração com APIs Bancárias para a emissão de cobranças representa um avanço estratégico para empresas que buscam automatizar e otimizar sua gestão financeira. Ao conectar diretamente o SGP às instituições bancárias, elimina-se a necessidade de processos manuais, como geração de arquivos de remessa e importação de retornos, reduzindo significativamente erros operacionais e retrabalhos.

Entre os principais benefícios dessa integração destacam-se:

• Automatização do processo de cobrança: o boleto é emitido e registrado automaticamente no banco a partir do SGP, garantindo maior agilidade e conformidade com as regras bancárias.

• Redução de erros e inconsistências: a comunicação direta evita falhas comuns em processos manuais, como duplicidade de boletos ou divergências de valores.

• Retornos instantâneos ou em até 15 minutos: a confirmação do pagamento via PIX ocorre em tempo real (ou no máximo em 15 minutos, conforme regulamentação do BACEN), permitindo atualização imediata dos recebimentos no sistema.

• Maior segurança e confiabilidade: os dados são transmitidos de forma padronizada e segura, minimizando riscos de fraudes ou informações incorretas.

• Controle centralizado: todas as informações financeiras ficam concentradas no SGP, facilitando o acompanhamento de recebimentos e inadimplência.

• Agilidade na tomada de decisão: relatórios atualizados permitem uma visão clara da saúde financeira da empresa.

Assim, a integração bancária não apenas simplifica o processo de cobrança, mas também proporciona maior eficiência operacional, segurança e controle estratégico sobre o fluxo de caixa da organização.

Antes de iniciar o processo, consulte nossa FAQ – Atenção à Segurança da sua Integração! para garantir uma implementação mais segura e eficiente.

2. Dados necessários para integrar ao SGP

Nesta etapa, será realizado o cadastro do portador, etapa fundamental para a correta emissão dos boletos.

Requisitos obrigatórios:

• Número da Agência;

• Número da Conta com Dígito;

• Número da carteira (Se diferente de 109);

• Já gerou títulos a partir dessa conta no banco ou em outro sistema?

  • Se sim, qual a quantidade de boletos gerados?

Atenção: Os dados cadastrados serão utilizados diretamente na geração dos boletos.
Isso significa que informações como nosso número, código de barras e linha digitável dependem totalmente da configuração realizada neste cadastro.

3. Integração do Portador

Mesmo sendo uma integração via API, os dados da conta são necessários para a emissão dos boletos.

Na guia Dados Bancários configure os campos abaixo com os dados fornecido pelo banco:

Caso já existam boletos emitidos para essa conta, será necessário ajustar o campo “Nosso Número Sequência” na guia Parametrizações do Boleto no Portador.
Para isso, consulte junto ao seu banco qual foi o último “Nosso Número” gerado, garantindo a continuidade correta da numeração e evitando rejeições no registro dos boletos.

Em seguida, na guia Relacionamentos da Empresa selecione:

Confirme essas informações com o cliente para evitar rejeição de boletos por dados incorretos.

Por fim, devemos configurar os Juros e Multa, acessando a guia Juros, Multas, Descontos e Taxas

O Itaú aceita apenas as opções:

Para uma melhor compreensão, recomendamos a leitura da nossa documentação de Configuração de Juros e Multa

4. Ponto de Recebimento (Caixa)

O ponto de recebimento é o local onde os pagamentos de boletos serão registrados. 

5. Homologação e Emissão de Remessa

Finalizando o processo de integração do portador é recomendado passar pelo processo de  homologação bancária. Esse processo se resume ao teste de emissão de boletos e envio da remessa de títulos ao banco para validarem os dados, se tiver dúvidas na geração da remessa, verifique o seguinte vídeo: Arquivo de remessa e retorno .

Nesse processo não é obrigatório o processo de registro de boletos, o banco possui ferramentas para validação do layout da remessa e dos boletos.

Sugestão: Para validação da primeira remessa de teste, gerar 5 boletos de 20,00 cada.

Após gerar os boletos é necessário criar a remessa, seguindo o passo a passo abaixo:

• No Menu Principal, acesse Financeiro (❶), depois vá em Títulos (❷) e, em seguida, clique em Remessa (❸) e em Arquivo de Cobrança (❹)

Nesse menu devemos selecionar o  Portador emissor dos boletos, a Data Inicial e a Data Final , indicando o vencimento do primeiro boleto e o do último, no Modelo de Arquivo devemos selecionar o CNAB correspondente e em Ocorrências iremos definir a 01 - Registro de Títulos

Após a homologação da remessa, o SGP estará apto a emitir boletos para registro manual.

Caso deseje automatizar o processo de registro e retorno por meio de integração, basta prosseguir para a etapa de integração com a API do Gateway.

6. Cadastro do Gateway de Boleto Hibrido

Nesta etapa da documentação, abordaremos a integração da API bancária do Banco Itaú para registro de Boleto Hibrido e PIX.

As credenciais usadas para integração devem geradas com auxilio do suporte do banco.

Para realizar essa integração, serão necessários alguns dados e arquivos, como:

• Client ID

• Token Bearer
• Chave PIX

Os dados acima correspondem às informações base enviadas pelo Itaú. A partir delas, é necessário seguir o processo indicado pelo banco para gerar as demais credenciais listadas a seguir:

• Client Secret 
• Certificado PFX 

Com os dados em mãos, podemos integrar o Gateway ao SGP para emissão de boletos.

Clique no botão Cadastrar e preencha da seguinte forma:

7. Cadastro do Gateway de PIX

O caminho de acesso é o mesmo do cadastro de Gateway de Boleto, apenas devemos ajustas os dados preenchidos.

Esse modelo de integração é apenas para emissão de QRCode PIX, caso queira uma integração de Boleto Hibrido, verifique a seção anterior.

Clique no botão Cadastrar e preencha da seguinte forma:

Antes de cadastrar a URL de notificação, verificar a URL verificar a seção de Informações Adicionais

Imagem de Referência (API PIX)

 

8. Informações Adicionais

 

Para essa integração existem dois tipos de PIX o  Pix Cob e Pix CobV :

• Pix Cob : Gera um QR Code para pagamento imediato, sem data de vencimento. Ideal para pagamentos instantâneos e avulsos. Nessa modalidade, no SGP esse PIX expira no dia do vencimento do boleto. Sendo possivel usar o parâmetro abaixo para gerar um novo pix atualizado após expirar.

  forcar_atualizacao_pix=1

• Pix CobV (Cobrança com Vencimento) : Permite definir uma data de vencimento e aplicar juros, multas e descontos. Usado para cobranças recorrentes, como boletos. Nessa modalidade, no SGP o PIX acompanha o "vencimento" do boleto atualizando Multa e Juros diários. Pode ser habilitado com o uso do seguinte parâmetro:

  pixvencimento=1

Como essa Integração não possui Retorno Automático de Código de Barras é preciso cadastrar um novo Gateway seguindo o processo do nosso Guia de Integração | Itaú Retorno Automático