Integração Itaú

A integração com o Itaú liga a conta PJ da sua empresa ao sistema. As cobranças das vendas saem como PIX ou como boleto registrado, e o dinheiro cai direto na conta, pela tarifa que você já tem com o banco.

O que a integração faz

PIX. Gera a cobrança com QR Code e copia e cola. A chave PIX é a da conta do Itaú.
Boleto registrado. O boleto é registrado no banco na hora, na carteira de cobrança da empresa. O sistema gera o PDF do boleto, e o cliente paga pelo código de barras ou pela linha digitável.
Boleto com QR Code PIX (Bolecode). Com a chave PIX informada na forma de pagamento do boleto, o mesmo boleto pode ser pago também por PIX, pelo QR Code ou pelo copia e cola.
Baixa automática. O sistema consulta o banco e dá baixa no pedido quando o pagamento aparece.
Cancelamento. Cancelar a transação no sistema baixa o boleto no banco, ou remove a cobrança PIX, e ela deixa de aceitar pagamento.

A integração não processa cartão. Para cartão, use um gateway (veja Integrações de Pagamento).

O que você precisa antes de começar

Item	Onde conseguir	Para quê
Liberação da API Pix Recebimentos e da API de Cobrança (Cash Management)	Gerente da conta no Itaú	PIX e boleto
Client ID e token temporário	Enviados pelo banco depois da liberação	Gerar o certificado
Client Secret, certificado (.crt) e chave privada (.key)	Portal Itaú for Developers, ao gerar o certificado dinâmico	PIX e boleto
Chave PIX da conta no Itaú	Aplicativo ou internet banking do banco	PIX
Código do beneficiário (agência, conta e dígito) e carteira de cobrança	Contrato de cobrança, com o gerente da conta	Boleto
Liberação da cobrança com QR Code (Bolecode) na mesma credencial	Gerente da conta no Itaú	Boleto com QR Code PIX

Quem só vai cobrar por PIX não precisa da carteira de cobrança. Quem só vai emitir boleto sem QR Code não precisa da chave PIX.

Passo 1: pedir a liberação ao banco e gerar o certificado

No Itaú a credencial é liberada pelo banco, para o CNPJ titular da conta.

Peça ao gerente da conta a liberação da API Pix Recebimentos, da API de Cobrança (Cash Management) ou das duas, conforme o que vai usar. Para o boleto com QR Code PIX, peça também a cobrança com QR Code (Bolecode) na mesma credencial da cobrança: a consulta e a baixa desse boleto usam a API de Cobrança. O banco envia o Client ID e um token temporário.
Acesse o portal Itaú for Developers e abra a área de Certificado dinâmico.
Gere o certificado informando o Client ID e o token temporário. O portal entrega o Client Secret, o arquivo do certificado (.crt) e o arquivo da chave privada (.key). Guarde os três: a chave privada não é mostrada de novo.

O certificado vale 1 ano. Antes de vencer, renove no portal e envie o novo arquivo na conexão, senão as cobranças param de funcionar.

Passo 2: conectar no sistema

No menu lateral, clique em Sistema e em Integrações.
Busque por “Itaú” e clique em Conectar.
Preencha a janela:

Campo	O que informar
Nome da conexão	Como a conta aparece nas telas do sistema
Client ID e Client Secret	As credenciais entregues pelo banco e pelo portal
Certificado (.crt) e Chave privada (.key)	Os dois arquivos do certificado dinâmico. Obrigatórios em produção
Ambiente de Conexão	Produção para cobrar de verdade, Homologação para testar com as credenciais do sandbox do portal

Clique em Conectar e testar conexão. O sistema pede um acesso ao banco com as credenciais: se elas estiverem erradas, a mensagem do banco aparece na tela.

Passo 3: ligar à forma de pagamento

Conectar não basta: cada forma de pagamento precisa apontar para a integração.

Clique em Vendas, depois em Pagamentos e em Formas de Pagamento.
Abra (ou crie) a forma do tipo PIX ou Boleto e vá para a aba Pagamento Online.
No campo Integração, escolha a conexão do Itaú.
No PIX, preencha a Chave PIX da conta do Itaú.
No boleto, preencha o Código do beneficiário e a Carteira. Os dois são obrigatórios: sem eles a forma de pagamento não salva. A Chave PIX do boleto é opcional: preenchida, o boleto é registrado com QR Code PIX; em branco, sai só com código de barras.
Ative Disponível no checkout online e salve.

O Código do beneficiário tem 12 dígitos, sem ponto nem traço: a agência (4 dígitos), a conta (7 dígitos, completando com zeros à esquerda) e o dígito verificador (1 dígito). A agência 0123 com a conta 45678-1 fica 012300456781. A Carteira tem até 3 dígitos. A mais comum é a 109.

Faça isso uma vez para o PIX e outra para o boleto. O passo a passo completo da tela está em Integrações de Pagamento.

Como a baixa acontece

Nesta integração o pagamento não chega por aviso do banco. É o sistema que consulta o Itaú:

PIX: a cobrança pendente é consultada a cada sincronização automática das transações, até ser paga ou expirar.
Boleto ainda não vencido: é consultado a cada 6 horas.
Boleto vencido que ainda aceita pagamento: é consultado a cada sincronização automática.

Para não esperar, abra Vendas > Pagamentos > Transações, selecione a transação e clique em Sincronizar: o sistema consulta o banco na hora.

Regras e limites

Nosso número: é gerado pelo sistema, com 8 dígitos, dentro da carteira informada na forma de pagamento. Se o banco avisar que o número já existe, gere o boleto de novo.
Boleto em PDF: o banco registra o boleto e não fornece o arquivo. O sistema gera o PDF, com a linha digitável e o código de barras que o banco devolveu, no layout Boleto bancário dos relatórios, que pode ser personalizado. Na tela de pagamento o cliente clica em Abrir Boleto para ver o PDF ou em Copiar para levar a linha digitável ao aplicativo do banco dele.
Boleto com QR Code PIX: sai quando a forma de pagamento do boleto tem a Chave PIX do boleto preenchida. A chave precisa estar registrada na conta do Itaú e a cobrança com QR Code precisa estar liberada pelo banco. Na tela de pagamento o cliente vê o QR Code e o botão Copiar do código PIX, além do boleto. O QR Code não aparece no PDF.
Boleto sem QR Code PIX: com a Chave PIX do boleto em branco, o boleto sai só com código de barras e linha digitável.
Link do boleto: abre sem login enquanto a cobrança está pendente. Depois de paga ou cancelada, o link mostra o aviso “Este boleto não está mais em aberto”.
Pagador do boleto: o banco exige nome, CPF ou CNPJ e endereço com CEP. Com o cadastro do cliente incompleto, o banco recusa o boleto e a mensagem dele aparece na tela.
Pagador do PIX: o cliente vai identificado pelo CPF ou CNPJ do cadastro.
Pagamento depois do vencimento: sem prazo configurado, vale o prazo do cadastro da cobrança no banco. Com Dias para pagar após o vencimento preenchido, o boleto aceita pagamento até o fim do prazo. Veja Formas de Pagamento.
Juros e multa: nesta integração o boleto sai sem juros e multa, e o sistema não deixa salvar a forma de pagamento do boleto com Juros ao mês (%) ou Multa (%) preenchidos.
Valor do boleto: o boleto só aceita o pagamento do valor exato.
Homologação: nesse ambiente o boleto, com ou sem QR Code, é enviado ao banco só para conferência dos dados, sem registro. Serve para validar as credenciais, não para cobrar.

Problemas comuns

A cobrança falha pedindo certificado: a conexão está em Produção sem o certificado dinâmico. Envie o certificado (.crt) e a chave privada (.key) na conexão.

O banco recusa as credenciais: confira se o Client ID e o Client Secret são do mesmo ambiente escolhido em Ambiente de Conexão e se o certificado enviado foi gerado para esse Client ID.

“Acesso a rota não permitido”: a credencial não tem a API que a cobrança usa. O PIX precisa da API Pix Recebimentos, o boleto da API de Cobrança (Cash Management) e o boleto com QR Code da cobrança com QR Code (Bolecode). Peça ao gerente a liberação da que falta, ou deixe a Chave PIX do boleto em branco para emitir o boleto sem QR Code.

O boleto falha pedindo o código do beneficiário ou a carteira: a forma de pagamento do boleto foi salva antes de ser ligada ao Itaú e ficou sem os dados da cobrança. Abra a forma, preencha os dois campos na aba Pagamento Online e salve.

As cobranças pararam de funcionar de uma hora para outra: o certificado dinâmico venceu. Renove no portal do banco e envie o novo arquivo na conexão.

O cliente pagou e o pedido continua em aberto: use Sincronizar na transação. Se o banco ainda mostrar o boleto em aberto, a compensação não terminou.

Veja também

Hub de Integrações: conectar, pausar e excluir uma conexão
Integrações de Pagamento: como escolher banco ou gateway
Transações: acompanhar e sincronizar as cobranças