Itaú (341): boleto, Bolecode e o certificado que só o Itaú usa
O Itaú é o único banco que NÃO aceita o certificado A1 da empresa: ele exige um certificado emitido pelo próprio Itaú, chamado Certificado Dinâmico. Este artigo mostra o que pedir ao banco, como o identificador do beneficiário é montado a partir de agência, conta e dígito, e a carteira que precisa ter exatamente três dígitos.
Quando usar
Use ao configurar a conta Itaú pela primeira vez, ou quando a emissão falhar dizendo que o certificado não foi emitido pelo STS.
Antes de começar
- Acesso ao Itaú for Developers, solicitado ao gerente PJ.
- Contrato de Cash Management com a API de boletos.
- Certificado Dinâmico gerado pelo assistente do Hap - o A1 da empresa não serve.
O que essa integração faz
O Itaú emite, consulta, altera e baixa boletos, devolve o PDF junto com a emissão e suporta o Bolecode - o boleto com Pix integrado, que sai automaticamente quando há chave Pix configurada. O webhook de liquidação é registrado sozinho ao salvar a conta.
| Recurso | Como funciona |
|---|---|
| Boleto | Emitir, consultar e baixar. A alteração de vencimento também funciona pela API. |
| PDF do boleto | Vem junto com a resposta da emissão. |
| Bolecode | Boleto com Pix integrado, gerado automaticamente quando há chave Pix configurada. |
| Webhook | Registrado sozinho ao salvar a conta, para notificar a liquidação. |
| Pix avulso | Não suportado. |
| Pagamento de contas | Não suportado. |
O que pedir ao Itaú
- 1
Solicite ao gerente Itaú PJ o acesso ao Itaú for Developers.
- 2
Contrate o Cash Management com a API de boletos.
- 3
O Itaú envia por e-mail o Client ID e um token temporário, válido por 7 dias corridos - é com ele que o certificado é gerado.
- 4
Anote a agência com 4 dígitos, a conta com 7 dígitos e o dígito verificador. O Hap junta os três para montar o identificador do beneficiário.
- 5
Gere o Certificado Dinâmico pelo assistente do Hap, no convênio da conta Itaú.
Preencher o convênio no Hap
| Campo no formulário | O que preencher |
|---|---|
| Agência (obrigatório) | 4 dígitos. Fica na aba de dados da conta bancária. |
| Conta (obrigatório) | 7 dígitos. Fica na aba de dados da conta bancária. |
| Dígito da conta (obrigatório) | 1 dígito. Junto com agência e conta, forma o identificador do beneficiário. |
| Carteira (obrigatório) | Exatamente 3 dígitos. Se estiver em branco, o Hap usa 109, que é a cobrança simples com registro. |
| Client ID (obrigatório) | Gerado no Itaú for Developers. |
| Client Secret (obrigatório) | Devolvido junto com o certificado, no assistente. |
| Ambiente (obrigatório) | Sandbox ou Produção. |
| Arquivo .crt e .key | Obrigatórios em produção. Saem do assistente de Certificado Dinâmico. |
| Senha do certificado | Apenas se a chave estiver protegida por senha. |
Problemas comuns
- A emissão falha dizendo que o certificado não foi emitido pelo STS: você tentou usar o A1 da empresa. O Itaú só aceita o Certificado Dinâmico dele. Use o assistente - não há como contornar.
- Erro reclamando da carteira: o Itaú exige exatamente três dígitos. As carteiras comuns são 109, 112, 175, 188 e 198. Se não souber a sua, 109 é a de cobrança simples com registro.
- O token temporário expirou: ele vale 7 dias corridos a partir do envio. Peça outro ao responsável pela API no Itaú.
- A consulta logo depois de cancelar ainda mostra o boleto em aberto: o Itaú leva alguns segundos para propagar. O Hap protege contra isso - um título já baixado não volta a aberto por causa de uma consulta atrasada.
- O endereço da API não responde em produção: as URLs variam conforme o contrato. Confirme com o responsável pela API no Itaú qual é a do seu contrato.