Integração Boleto Itaú V2

O que é e para quê serve?

O Webservice Itaú é uma forma eficiente de registrar boletos. Ele realiza o envio imediato de informações para que o registro do boleto seja realizado, pois está integrado diretamente ao sistema do banco.

O Webservice Itaú 2.0 é uma versão atualizada da plataforma de integração de sistemas do Banco Itaú, destinada a facilitar a comunicação entre sistemas externos e os sistemas do banco. Webservices são conjuntos de protocolos e padrões que permitem a comunicação entre diferentes aplicações pela internet.

Essa versão 2.0 pode trazer melhorias em termos de desempenho, segurança, e talvez novas funcionalidades em comparação com versões anteriores. No entanto, detalhes específicos sobre o Webservice Itaú 2.0, como sua implementação técnica e suas características precisas, podem variar e serem obtidos diretamente com o Banco Itaú ou através da documentação oficial disponibilizada por eles.

Para quem é?

Essa funcionalidade pode ser utilizada por empresas que possuem conta no Itaú, que realizam cobranças via boleto e que possuem a carteira 109 contratada junto ao banco.

Como começar a usar?

O Webservice Itaú 2.0 provê uma série de serviços e funcionalidades, tais como consultas de saldo, extrato, transferências, pagamentos, entre outros, que podem ser integrados em sistemas de terceiros, como por exemplo, sistemas de gestão financeira de empresas, aplicativos de celular, entre outros.

Para integrar o Webservice Itaú 2.0 em um sistema, você geralmente precisará seguir estes passos básicos:

Cadastro e Autorização: Entre em contato com o Banco Itaú para obter autorização e credenciais de acesso ao Webservice Itaú 2.0. Você provavelmente precisará de uma conta no banco e passar por algum processo de autorização.

Entendimento da Documentação: O Banco Itaú geralmente fornece documentação detalhada sobre como usar seu Webservice, incluindo os endpoints disponíveis, os formatos de dados suportados (como JSON ou XML), os parâmetros necessários para cada tipo de requisição, e os padrões de segurança que devem ser seguidos.

Documentação Itaú:
login Itaú for developers

itaú for developers - geração do certificado dinâmico

Implementação da Integração: Com base na documentação fornecida pelo Banco Itaú, você precisará implementar a integração em seu sistema. Isso pode envolver o uso de bibliotecas ou SDKs fornecidos pelo banco, ou você pode optar por fazer chamadas HTTP diretamente para os endpoints do Webservice.

Testes: Antes de colocar o sistema em produção, é crucial realizar testes rigorosos para garantir que a integração esteja funcionando corretamente. O Banco Itaú geralmente oferece ambientes de teste (sandbox) para que você possa realizar esses testes sem afetar dados reais.

Implantação em Produção: Depois de testar e garantir que a integração esteja funcionando conforme o esperado, você pode implantar o sistema em produção e começar a usar o Webservice Itaú 2.0 em seu ambiente de produção.

Lembre-se de que a integração com qualquer Webservice, incluindo o Webservice Itaú 2.0, requer cuidado e atenção aos detalhes, especialmente em relação à segurança e à conformidade com as políticas do banco. Certifique-se de seguir as práticas recomendadas e de manter-se atualizado sobre eventuais alterações ou atualizações no serviço.

Para começar a utilizar o serviço é necessário ter a carteira 109 de boletos com registro e solicitar ao gerente do banco as seguintes credenciais de acesso:

• Layout:
• Agência:
• Conta Corrente: 
• Carteira:
• Itaú Chave:
• Client ID:
• client_secret:

O Funcionamento é muito parecido com o Boleto v1 do Itaú, a forma de emitir e retorno continuam da mesma forma nessa primeira versão da Vindi o que muda é o processo de integração inicial e um campo extra beneficiário.

O cliente deve ter uma chave de integração junto ao banco Itaú, que chamamos de private_key_jwt e gerar seu certificado para poder transacionar.

Fluxo de geração da credencial e certificado assinado pelo Itaú

Esse processo deve ser feito pelo cliente junto com a equipe e banco, onde serão necessários gerar as credenciais mais o certificado dinâmico necessários para que a aplicação da Vindi consiga se comunicar junto a API do Itaú, esse certificado precisa de uma chave que o banco disponibiliza e deve seguir um processo para geração.

Ambas as chaves são criadas pelo desenvolvedor que irá integrar com as APIs do Itaú. A chave privada, deve ser criada e armazenada de maneira segura dentro do ambiente da aplicação, que consumirá as APIs e é utilizada para assinar todas as obtenções de access_tokens. 

A chave pública deve ser exposta em um terminal de configuração descoberta (well-known endpoint) em uma sessão específica conhecida como jwks_uri (JSON Web Key Sets – URI). A jwks_uri deve ser informada para o agente comercial Itaú no momento da contratação. 

Saiba mais em JSON Web Key Sets

Com o certificado em mãos basta subir na configuração do credenciamento junto com a chave (private_key_jwt) e poderá começar a emitir.

Para estabelecer conexão segura com os API Gateways do Itaú é necessário enviar um client certificate. Este certificado é usado para estabelecer o mTLS (OAuth 2.0 Mutual Transport Layer Security - https://tools.ietf.org/html/rfc8705):

1. A partir de um client_id e token temporário para ativação, ambos fornecidos pelo agente comercial após a contratação, o desenvolvedor gera um arquivo CSR (Certificate Signing Request) baseado em um template e documentação será fornecida no nosso Portal do Desenvolvedor;

2. O desenvolvedor solicita um certificado assinado pelo Itaú (CRT – Certificate File) , através de uma API informando o CSR e token temporário de ativação; Tutorial completo de geração do certificado: (https://devportal.itau.com.br/certificado-dinamico)

3. A renovação automática e revogação estão também documentadas no Portal do Desenvolvedor.

4. O cliente com o credenciamento informa o arquivo CRT e o private_key_jwt para poder autenticar e começar a emitir.

Vale ressaltar que o certificado tem duração de 01 ano, para renovar precisa realizar uma nova chamada de api.

Fluxo de autenticação e credenciamento

Para o cadastro do gateway na Vindi, as informações abaixo são necessárias:

As credenciais abaixo são pré requisitos para o cadastro do gateway do Boleto Itaú V2 na Vindi:

• Client: é a informação de client_id, Identificador único e público de uma aplicação no fluxo de autenticação do Itaú. É fornecida pelo banco após a contratação do serviço.
• Secret: é a informação de client_secret, é uma chave segredo conhecido somente pela aplicação e o servidor de autorização a qual pertence a um client_id. O client_secret precisa ser gerado para o fluxo de autenticação
• Certificate: é o certificado CRT que contém as informações e assinaturas de ambas as partes envolvidas (consumidor da API e Itaú)
• Private key: é a informação que contém a chave privada do certificado.
• Beneficiary: são os dados do beneficiário do boleto, sendo composto por Código Agência (4 dígitos) + Conta (7 dígitos) + DAC (1 dígito). Exemplo: 150000123450

É importante ressaltar que as credenciais de Secret, Certificate e Private Key são geradas a partir de um passo a passo estabelecido entre o cliente e o Itaú.

Todos os conceitos e fluxo de geração das credenciais estão descritos na documentação do banco https://devportal.itau.com.br/certificado-dinamico e deve ser feito pelo time técnico do cliente.

Campo de beneficiário no gateway da Vindi

Um campo extra na nova integração: Campo de beneficiário (dados da conta do crédito). Trazemos no gateway por conta de que o Itaú prevê um roadmap de lançamentos de funcionalidades que serão utilizadas sem a necessidade do Cnab. Ou seja, tudo via gateway.

O layout do CNAB vai ser diferente?

Não, o CNAB continua sendo o layout 400 com o mesmo tipo de retorno, não alterando nada da versão 1.0

Emissão com caracteres personalizados * [ ] $ @ # ( )

O boleto não aceita campos com caracteres personalizados como * [ ] $ @ # ( ).
Caso haja caracteres personalizados será feita a remoção automaticamente do caráter evitando a recusa, porém em alguns casos pode ocorrer um erro na emissão do boleto.

O que vai acontecer com a versão antiga?

Ela continuará existindo, mas como uma versão legada, todos os novos clientes serão credenciados na v2. Clientes que estão já credenciados na v1 podem a qualquer momento migrar para a v2, basta procurar o Gerente de conta deles no Itaú e pedir a geração de chave e certificado para credenciar na v2.

Quem optar por não migrar da v1 para a v2 neste momento não terá nenhum impacto previsto a médio prazo, além de não ter mais manutenção da api e benefícios futuros.

Outras informações importantes:

Alterações e cancelamentos: é importante destacar que a conexão instantânea do webservice oferecida pelos bancos serve apenas para registro dos boletos. Sempre que for necessário alterar ou cancelar um boleto, será preciso gerar manualmente um arquivo de remessa, bem como importar o arquivo de retorno na plataforma.

Multa e Juros
A nova integração do Itaú v2 não aceita multa e juros com valor menor que 0,1 centavo, caso o valor seja menor ele irá ignorar, recomendamos nesses casos arredondar para 0,1 centavo.

Migração de V1 para V2 na Vindi
Caso já esteja integrado com o Boleto V1 Itaú na Vindi, precisará ser analisado o fluxo de conciliação antes do credenciamento, entendendo o seu NSU para não haver duplicidade de aprovações e conciliação equivocadas.
Caso o cliente seja novo e não tenha movimentações na V1 sua integração seguirá normalmente.