Itaú for Developers - Tutorial: Atualize a cadeia de certificados das APIs do Itaú

Introdução

O Itaú está atualizando a cadeia de certificados digitais utilizada em suas APIs.

Se sua empresa consome APIs do Itaú, é importante atualizar a configuração de certificados do seu ambiente dentro do prazo informado para manter a comunicação funcionando normalmente.

Fluxo de atualização da cadeia de certificados

Siga o caminho abaixo de acordo com o resultado de cada verificação.

Etapa ou decisão Requer atenção Correção necessária Sucesso

Início

Endpoint afetado?

Não

Nenhuma ação necessária

Sim

Identificar nova URL

Baixar bundle da nova CA

Configurar firewall outboundIPs atuais e novos

Importar nova cadeia de certificados

Validar no ambiente real da aplicação

HTTP 200?

Não

Revisar certificadosFirewall, proxy e rede

Após corrigir, retorne para Validar no ambiente real da aplicação.

Sim

Ambiente pronto

Atualizar URL da aplicação

Executar testes funcionais

Atualização concluída

O que você precisa fazer?

Consulte o cronograma de migração e atualize a cadeia de certificados do seu ambiente antes da data correspondente ao endpoint utilizado pela sua integração.

Importante

Aplicações que não reconhecerem a nova cadeia de certificados poderão apresentar falhas de conexão após a migração.

Consulte o cronograma completo e baixe o bundle de certificados.

Cronograma e downloads

Quem precisa realizar a atualização?

Você precisa realizar essa atualização se sua solução consome APIs do Itaú, incluindo integrações de:

Pix;
Boletos;
Pagamentos;
Open Finance;
Câmbio;
Outras APIs disponibilizadas pelo Itaú.

Quais as URLs impactadas?

De acordo com o endereço impactado utilize a respectiva URL de validação:


  https://secure.gateway.api.itau/sandbox/ca-validation
  https://api.gateway.itau.com.br/sandbox/ca-validation
  https://api-bin.gateway.itau.com.br/sandbox/ca-validation

O que pode acontecer se a atualização não for realizada?

Após a migração de cada endpoint, aplicações que não reconhecerem a nova cadeia de certificados poderão apresentar falhas de conexão TLS/SSL. Os erros mais comuns são:

SSL certificate verify failed
PKIX path building failed
unable to get local issuer certificate
CERT_UNTRUSTED
The remote certificate is invalid

Se isso acontecer, a comunicação com as APIs poderá ser interrompida até que a atualização seja concluída.

Atualize o CA

Escolha a opção no índice ao lado que mais se aproxima da sua infraestrutura e siga o tutorial correspondente.

Windows Server

A seguir, descrevemos os procedimentos para importação da nova cadeia de certificados no ambiente Windows Server. Existem três métodos disponíveis: via interface gráfica (MMC), via PowerShell e via certutil. Escolha o que melhor se adequa ao seu cenário.

Nota

Todos os procedimentos abaixo exigem privilégios de Administrador. Certifique-se de executar as ferramentas com elevação de permissão ("Executar como Administrador").

Importação via MMC

Este é o método gráfico recomendado para quem prefere uma interface visual.

Abrir o MMC e adicionar o Snap-in de Certificados

Pressione Win + R, digite mmc e pressione Enter.
No menu superior, clique em Arquivo ? Adicionar/Remover Snap-in... (ou Ctrl + M).
Na lista da esquerda, selecione Certificados e clique em Adicionar >.
Selecione Conta de computador e clique em Avançar.
Mantenha Computador local e clique em Concluir.
Clique em OK. A árvore exibirá o nó Certificados (Computador Local).

Importar a nova Root CA

Expanda Certificados (Computador Local) ? Autoridades de Certificação Raiz Confiáveis ? Certificados.
Clique com o botão direito na pasta Certificados e selecione Todas as Tarefas ? Importar....
Na tela de boas-vindas, clique em Avançar.
Clique em Procurar... e selecione o arquivo root-ca.crt (extraído do Certificate Bundle do Developer Portal Itaú).
Confirme que o repositório é Autoridades de Certificação Raiz Confiáveis.
Clique em Avançar e Concluir.

Importar o Certificado Intermediário

Expanda Certificados (Computador Local) ? Autoridades de Certificação Intermediárias ? Certificados.
Clique com o botão direito na pasta Certificados e selecione Todas as Tarefas ? Importar....
Repita o processo anterior, mas selecione o arquivo intermediate-ca.crt.
Confirme que o repositório é Autoridades de Certificação Intermediárias e finalize.

Atenção

Não remova os certificados da cadeia anterior durante o período de transição. As duas cadeias devem coexistir até que o Itaú comunique oficialmente a desativação da cadeia antiga.

Importação via PowerShell

Abra o PowerShell como Administrador.

Importar a Root CA

powershell

Import-Certificate `
    -FilePath "C:\caminho\para\root-ca.crt" `
    -CertStoreLocation Cert:\LocalMachine\Root

Importar o Certificado Intermediário

powershell

Import-Certificate `
    -FilePath "C:\caminho\para\intermediate-ca.crt" `
    -CertStoreLocation Cert:\LocalMachine\CA

Nota

O parâmetro Cert:\LocalMachine\Root corresponde a "Autoridades de Certificação Raiz Confiáveis" e Cert:\LocalMachine\CA às "Autoridades de Certificação Intermediárias".

Verificar a importação

Para confirmar a presença da nova Root CA:

powershell

Get-ChildItem -Path Cert:\LocalMachine\Root | `
    Where-Object { $_.Subject -like "*Itau*" } | `
    Format-List Subject, Thumbprint, NotBefore, NotAfter

Para o certificado intermediário:

powershell

Get-ChildItem -Path Cert:\LocalMachine\CA | `
    Where-Object { $_.Subject -like "*Itau*" } | `
    Format-List Subject, Thumbprint, NotBefore, NotAfter

Exemplo de saída esperada:

Subject    : CN=Itau Intermediate CA, O=Itau Unibanco S.A., C=BR
Thumbprint : A1B2C3D4E5F6...
NotBefore  : 01/01/2025 00:00:00
NotAfter   : 31/12/2030 23:59:59

Nota

Substitua "*Itau*" pelo Common Name (CN) exato presente nos certificados, caso necessário.

Importação via certutil

O certutil é uma ferramenta de linha de comando nativa do Windows. Abra o Prompt de Comando como Administrador.

Importar a Root CA

cmd

certutil -addstore "Root" "C:\caminho\para\root-ca.crt"

Importar o Certificado Intermediário

cmd

certutil -addstore "CA" "C:\caminho\para\intermediate-ca.crt"

Saída esperada:

Root "Autoridades de Certificação Raiz Confiáveis"
O certificado "CN=..." foi adicionado ao repositório.
CertUtil: -addstore comando concluído com êxito.

Nota

Os nomes dos repositórios (Root e CA) são padrões do Windows e independem do idioma do sistema operacional.

Validação no Windows

Após a importação, valide se a nova cadeia está sendo reconhecida.

Opção A — Testar com curl

cmd

curl -v https://sts.itau.com.br

Procure por:

* SSL connection using TLSv1.2 / ...
* Server certificate:
*   subject: CN=sts.itau.com.br; ...
*   issuer: CN=Itau Intermediate CA; ...
*   SSL certificate verify ok.

Opção B — Testar com Invoke-WebRequest

powershell

try {
    $response = Invoke-WebRequest -Uri "https://sts.itau.com.br" -UseBasicParsing
    Write-Host "Status: $($response.StatusCode) - Conexao TLS bem-sucedida!" -ForegroundColor Green
} catch {
    Write-Host "Erro na conexao: $($_.Exception.Message)" -ForegroundColor Red
}

Opção C — Verificar a cadeia com certutil

cmd

certutil -verify -urlfetch "C:\caminho\para\intermediate-ca.crt"

Erros comuns no Windows

Erro	Causa provável	Solução
`CERT_E_UNTRUSTEDROOT`	A Root CA não foi importada no repositório correto ou a importação falhou silenciosamente.	Reimporte o `root-ca.crt` em Raiz Confiáveis e verifique com `Get-ChildItem Cert:\LocalMachine\Root`.
`SEC_E_UNTRUSTED_ROOT` / `0x80090325`	O intermediário foi importado, mas a Root CA está ausente.	Importe ambos: a Root CA em `Root` e o intermediário em `CA`.
`Access is denied`	Terminal sem privilégios de Administrador.	Reabra com Executar como Administrador.
`The specified file was not found`	Caminho do `.crt` incorreto ou arquivo não extraído do bundle.	Verifique o caminho completo e a extração do bundle.
`Cannot find object or property`	Certificado importado no Usuário Atual em vez do Computador Local.	No MMC, selecione Conta de computador. No PowerShell, use `Cert:\LocalMachine\...`.
`The underlying connection was closed`	TLS incompatível ou truststore não reconhece a cadeia.	Force TLS 1.2 com `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12`.
`A required certificate is not within its validity period`	Relógio do sistema desatualizado.	Sincronize via NTP: `w32tm /resync /force`.

Atenção

Após importar os certificados, pode ser necessário reiniciar os serviços de aplicação (IIS, Apache, serviços .NET etc.) para que reconheçam a nova cadeia.

Linux (Ubuntu/Debian e RHEL/CentOS)

As distribuições Linux utilizam diferentes mecanismos para gerenciar o trust store do sistema. A seguir, os procedimentos para as duas principais famílias.

Nota

Todos os comandos devem ser executados como root ou com sudo.

Ubuntu/Debian — trust store do sistema

Passo 1 — Copiar os certificados

bash

sudo cp root-ca.crt /usr/local/share/ca-certificates/itau-root-ca.crt
sudo cp intermediate-ca.crt /usr/local/share/ca-certificates/itau-intermediate-ca.crt

Nota

O diretório aceita apenas arquivos PEM com extensão .crt. Converta formatos DER com openssl x509 -inform DER -in root-ca.der -out root-ca.crt.

Passo 2 — Atualizar o trust store

bash

sudo update-ca-certificates

Saída esperada:

Updating certificates in /etc/ssl/certs...
2 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

Passo 3 — Confirmar a presença

bash

ls -la /etc/ssl/certs/ | grep -i itau

Atenção

Não remova os certificados da cadeia anterior durante o período de transição.

RHEL/CentOS/Amazon Linux — trust store do sistema

Passo 1 — Habilitar a gestão dinâmica (se necessário)

bash

sudo update-ca-trust enable

Passo 2 — Copiar os certificados para as âncoras

bash

sudo cp root-ca.crt /etc/pki/ca-trust/source/anchors/itau-root-ca.crt
sudo cp intermediate-ca.crt /etc/pki/ca-trust/source/anchors/itau-intermediate-ca.crt

Passo 3 — Atualizar o trust store

bash

sudo update-ca-trust extract

Nota

Diferente do Ubuntu/Debian, o comando não exibe saída detalhada. A ausência de erros indica sucesso.

Passo 4 — Confirmar a presença

bash

trust list | grep -i -A 3 "itau"

Validação no Linux

Teste 1 — curl

bash

curl -v https://sts.itau.com.br

Procure por SSL certificate verify ok. na saída.

Teste 2 — openssl s_client

bash

openssl s_client -connect sts.itau.com.br:443 -CApath /etc/ssl/certs/

Para RHEL/CentOS use o bundle consolidado:

bash

openssl s_client -connect sts.itau.com.br:443 -CAfile /etc/pki/tls/certs/ca-bundle.crt

O retorno Verify return code: 0 (ok) confirma que a cadeia é confiável.

Erros comuns no Linux

Erro	Causa provável	Solução
`curl: (60) SSL certificate problem: unable to get local issuer certificate`	A Root CA não foi importada ou o comando de atualização não foi executado.	Copie os certificados e execute `update-ca-certificates` (Debian/Ubuntu) ou `update-ca-trust extract` (RHEL/CentOS).
`curl: (77) error setting certificate verify locations`	Caminho do bundle incorreto ou pacote `ca-certificates` ausente (ex.: containers mínimos).	Instale `ca-certificates` e reimporte os certificados.
`Verify return code: 20`	OpenSSL não encontrou a Root CA no caminho informado.	Use o `-CApath`/`-CAfile` correto da distribuição.
`Verify return code: 2`	Certificado intermediário ausente ou corrompido.	Reimporte o intermediário e valide com `openssl x509 -in intermediate-ca.crt -text -noout`.
0 added em `update-ca-certificates`	Extensão diferente de `.crt`, formato DER ou diretório incorreto.	Confirme extensão `.crt` e formato PEM; copie para `/usr/local/share/ca-certificates/`.
`Permission denied`	Comando sem privilégios de superusuário.	Prefixe com `sudo` ou use `sudo su -`.
`certificate verify failed` em apps Python/Java/Node	Aplicação usa truststore próprio (certifi, cacerts) em vez do SO.	Configure `REQUESTS_CA_BUNDLE`, `keytool -importcert` ou `NODE_EXTRA_CA_CERTS` conforme a linguagem.

Atenção

Após a atualização do trust store, reinicie os serviços de aplicação. Conexões TLS já estabelecidas não serão afetadas até serem renovadas.

Microsoft Azure

A plataforma Azure oferece diversas formas de gerenciar certificados CA customizados, dependendo do serviço utilizado.

Atenção

Todos os procedimentos devem ser concluídos até 15 de setembro de 2026. Durante a transição, mantenha a cadeia atual junto com a nova.

Azure App Service

Permite adicionar certificados CA customizados ao truststore via Portal ou CLI.

Upload via CLI

bash

az webapp config ssl upload \
  --certificate-file ./root-ca.crt \
  --name <NOME_DO_APP_SERVICE> \
  --resource-group <RESOURCE_GROUP>

Variável WEBSITE_LOAD_ROOT_CERTIFICATES

Configure a variável com os thumbprints dos certificados importados para que o runtime os carregue no truststore.

bash

az webapp config appsettings set \
  --name <NOME_DO_APP_SERVICE> \
  --resource-group <RESOURCE_GROUP> \
  --settings WEBSITE_LOAD_ROOT_CERTIFICATES="<THUMBPRINT_ROOT>,<THUMBPRINT_INTERMEDIATE>"

Nota

Para carregar todos os certificados públicos, use o valor *. Em produção, prefira listar os thumbprints explicitamente.

Azure API Management

O APIM utiliza certificados CA para validar conexões TLS com backends.

bash

az apim certificate create \
  --resource-group <RESOURCE_GROUP> \
  --service-name <NOME_DO_APIM> \
  --certificate-id "itau-root-ca-nova" \
  --data @root-ca.crt

Nota

Após o upload, o APIM pode levar até 15 minutos para propagar os certificados. Planeje fora de janelas críticas.

Azure Key Vault

Solução recomendada para gerenciamento centralizado, permitindo que múltiplas aplicações referenciem os mesmos certificados.

bash

az keyvault certificate import \
  --vault-name <NOME_DO_KEY_VAULT> \
  --name "itau-root-ca-2026" \
  --file ./root-ca.crt

Nota

Com o Key Vault você centraliza o gerenciamento e rotaciona certificados sem redeploy das aplicações.

Azure Virtual Machines

Para VMs, o procedimento segue o do sistema operacional subjacente (Windows ou Linux).

Resumo rápido para Linux em Azure VM:

bash

sudo cp root-ca.crt /usr/local/share/ca-certificates/itau-root-ca.crt
sudo cp intermediate-ca.crt /usr/local/share/ca-certificates/itau-intermediate-ca.crt
sudo update-ca-certificates
curl -v https://sts.itau.com.br

Resumo rápido para Windows em Azure VM:

powershell

Import-Certificate -FilePath "C:\certs\root-ca.crt" -CertStoreLocation "Cert:\LocalMachine\Root"
Import-Certificate -FilePath "C:\certs\intermediate-ca.crt" -CertStoreLocation "Cert:\LocalMachine\CA"
Invoke-WebRequest -Uri "https://sts.itau.com.br" -UseBasicParsing

Liberação de IPs no Azure NSG

Se usa Network Security Groups para controlar tráfego de saída, libere os novos ranges de IP.

bash

az network nsg rule create \
  --resource-group <RESOURCE_GROUP> \
  --nsg-name <NOME_DO_NSG> \
  --name "Allow-Itau-API-Gateway" \
  --priority 100 --direction Outbound --access Allow --protocol Tcp \
  --destination-address-prefixes "3.44.192.200/29" \
  --destination-port-ranges 443 \
  --source-address-prefixes "*" --source-port-ranges "*"

Atenção

Mantenha as regras dos IPs antigos ativas durante a transição. Remova-as somente após confirmar a migração de todos os endpoints (após 15/09/2026).

Erros comuns no Azure

Erro	Serviço	Causa provável	Solução
`WEBSITE_FAILED_TO_LOAD_CERTIFICATE`	App Service	Thumbprint incorreto ou certificado não encontrado.	Verifique os thumbprints (sem `:`) e reinicie o App Service.
`SSL connection could not be established`	API Management	Certificados CA não importados ou backend não configurado.	Importe root e intermediário e verifique o backend.
`SecretNotFound / CertificateNotFound`	Key Vault	Identidade sem permissão ou nome incorreto.	Use `az keyvault set-policy` (get, list) e confira o nome.
`AuthorizationFailed - NSG Rule`	VNet / NSG	Regra de saída bloqueando os novos IPs.	Libere TCP/443 para `3.44.192.200/29` e `18.96.65.56/29`.
`CERT_UNTRUSTED`	App Service / VM	Nova Root CA ausente no truststore.	Importe `root-ca.crt` no truststore apropriado.
`Connection timed out`	Qualquer com NSG/Firewall	Firewall/NSG bloqueando saída.	Verifique NSG, Azure Firewall e UDR; libere porta 443.

Amazon Web Services (AWS)

A AWS oferece diversos serviços para gerenciamento de certificados e integração com APIs externas.

Atenção

Todos os procedimentos devem ser concluídos até 15 de setembro de 2026. Baixe o Certificate Bundle no Developer Portal Itaú antes de iniciar.

AWS API Gateway

Pode utilizar certificados CA customizados para validar conexões TLS com backends e para mTLS.

Atualizando truststores em S3 para mutual TLS

bash

aws s3 cp s3://<BUCKET>/truststore.pem ./truststore-atual.pem
cat root-ca.crt >> truststore-atual.pem
cat intermediate-ca.crt >> truststore-atual.pem
aws s3 cp ./truststore-atual.pem s3://<BUCKET>/truststore.pem

Nota

O truststore no S3 deve conter todos os certificados CA em PEM concatenado. Mantenha antigos e novos durante a transição.

AWS Certificate Manager (ACM)

bash

aws acm import-certificate \
  --certificate fileb://root-ca.crt \
  --region <REGIAO> \
  --tags Key=Name,Value=itau-root-ca-2026

Atenção

O ACM não gerencia truststores para conexões de saída (outbound). Para confiar na nova CA do Itaú, atualize o truststore na própria aplicação ou no SO da instância/container.

AWS Lambda + Layers

Funções Lambda não têm acesso direto ao SO. Use Lambda Layers + variáveis de ambiente.

bash

mkdir -p itau-ca-layer/certs
cp root-ca.crt intermediate-ca.crt itau-ca-layer/certs/
cat root-ca.crt intermediate-ca.crt > itau-ca-layer/certs/itau-ca-bundle.crt
cd itau-ca-layer && zip -r ../itau-ca-layer.zip . && cd ..
aws lambda publish-layer-version --layer-name itau-ca-certificates \
  --zip-file fileb://itau-ca-layer.zip \
  --compatible-runtimes python3.12 nodejs20.x java21 --region <REGIAO>

Configure as variáveis de ambiente da função:

SSL_CERT_FILE=/opt/certs/itau-ca-bundle.crt
NODE_EXTRA_CA_CERTS=/opt/certs/itau-ca-bundle.crt
REQUESTS_CA_BUNDLE=/opt/certs/itau-ca-bundle.crt

Nota

Os arquivos da Layer ficam em /opt/ no ambiente Lambda.

Amazon ECS / EKS

Inclua os certificados na imagem Docker ou via ConfigMap/Secret no Kubernetes.

dockerfile

FROM python:3.12-slim
COPY root-ca.crt /usr/local/share/ca-certificates/itau-root-ca.crt
COPY intermediate-ca.crt /usr/local/share/ca-certificates/itau-intermediate-ca.crt
RUN update-ca-certificates
ENV SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
ENV REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

Via ConfigMap no EKS:

bash

kubectl create configmap itau-ca-certificates \
  --from-file=itau-ca-bundle.crt=./itau-ca-bundle.crt \
  --namespace <NAMESPACE>

Security Groups e NACLs

bash

aws ec2 authorize-security-group-egress \
  --group-id $SG_ID \
  --ip-permissions IpProtocol=tcp,FromPort=443,ToPort=443,IpRanges='[{CidrIp=3.44.192.200/29}]'

Atenção

NACLs são stateless — crie regras de saída e de entrada (portas efêmeras 1024-65535). Security Groups são stateful e não exigem regras de retorno.

Erros comuns na AWS

Erro	Serviço	Causa provável	Solução
`CERTIFICATE_VERIFY_FAILED`	Lambda	Nova Root CA ausente no bundle da função.	Crie uma Layer e configure `SSL_CERT_FILE`/`NODE_EXTRA_CA_CERTS`.
`unable to verify the first certificate`	ECS / EKS	Container sem a nova cadeia no truststore.	Adicione `COPY` + `update-ca-certificates` no Dockerfile ou monte via ConfigMap.
`Connection timed out`	EC2 / ECS / Lambda	SG ou NACL bloqueando saída.	Libere TCP/443 para os novos ranges; em NACL, adicione regras de entrada efêmeras.
`PKIX path building failed`	ECS / EKS (Java)	Truststore Java (cacerts) sem a nova Root CA.	Use `keytool -importcert` no `cacerts`.
`self signed certificate in certificate chain`	Lambda (Node.js)	`NODE_EXTRA_CA_CERTS` ausente ou caminho inexistente.	Associe a Layer e defina `NODE_EXTRA_CA_CERTS=/opt/certs/itau-ca-bundle.crt`.
`SSLHandshakeException: No trusted certificate found`	API Gateway + VPC Link	Backend atrás do NLB não reconhece a nova cadeia.	Atualize o truststore no backend (EC2/ECS).

Plataformas SaaS

Plataformas SaaS abstraem a infraestrutura, mas integrações com APIs externas como as do Itaú podem exigir configurações específicas de certificados e rede.

Atenção

Em SaaS você frequentemente não tem acesso direto ao SO ou ao truststore. Os procedimentos focam nas opções de configuração disponíveis em cada plataforma.

Shopify

A Shopify gerencia automaticamente os certificados TLS das lojas. Para o funcionamento padrão, nenhuma ação é necessária.

Para apps customizados que chamam as APIs do Itaú:

Apps na infraestrutura Shopify: não é possível customizar o truststore; se necessário, acione o Suporte Shopify Partners.
Apps self-hosted: siga as instruções de Linux/Windows/Docker para atualizar o truststore do servidor.

Atualize URLs de callback antigas (api.itau.com.br) para as novas (api.gateway.itau.com.br) antes de 15/09/2026.

Salesforce

Use Named Credentials para configurar a integração e atualize a URL para o novo endpoint.

Certificate and Key Management: importe root-ca.crt e intermediate-ca.crt se a nova CA não for reconhecida automaticamente;
Remote Site Settings: adicione os novos endpoints (mantendo os antigos durante a transição);
CSP Trusted Sites: adicione os novos domínios para evitar bloqueios em componentes Lightning.

Teste via Apex:

apex

HttpRequest req = new HttpRequest();
req.setEndpoint('https://sts.itau.com.br');
req.setMethod('GET');
Http http = new Http();
HttpResponse res = http.send(req);
System.debug('Status: ' + res.getStatusCode());

ERPs Online (SAP, TOTVS, Oracle)

SAP Business Technology Platform (BTP)

Configure o Destination com a nova URL e importe os certificados em Security ? Trust Configuration.

Nota

Se usa TrustAll=true, a validação é ignorada — prática não recomendada em produção. Prefira TrustAll=false e importe a cadeia.

TOTVS Protheus

No appserver.ini, aponte o CACertFile para o bundle com a nova cadeia:

ini

[SSLConfigure]
TLS12=1
TLS13=1
CACertFile=C:\TOTVS\certs\itau-ca-bundle.crt
VerifyPeer=1
VerifyDepth=5

Oracle Integration Cloud (OIC)

Em Settings ? Certificates, faça upload de root-ca.crt e intermediate-ca.crt como Trust Certificates e atualize a Connection.

Erros comuns em SaaS

Erro	Plataforma	Causa provável	Solução
`UNABLE_TO_VERIFY_LEAF_SIGNATURE`	Shopify (app Node.js)	Truststore do servidor sem a nova Root CA.	Atualize o truststore e configure `NODE_EXTRA_CA_CERTS`.
`handshake_failure`	Salesforce (Apex)	Nova CA ausente ou URL não liberada.	Importe em Certificate and Key Management e adicione em Remote Site Settings.
`PKIX path building failed`	SAP BTP	`TrustAll=false` sem a cadeia importada.	Importe em Trust Configuration ou via SAP Cloud Connector.
`Erro no handshake SSL`	TOTVS Protheus	`CACertFile` não aponta para o bundle atualizado.	Atualize o `CACertFile` e reinicie o AppServer.
`ORA-29024: Certificate validation failure`	Oracle Integration Cloud	Trust Certificates desatualizados.	Faça upload da nova cadeia em Settings ? Certificates.
`Timeout` ao conectar	Qualquer SaaS com restrição de IP	IPs de saída fixos não alcançam os novos endpoints.	Verifique whitelisting de IPs da plataforma; libere os novos ranges.

Linguagens de Programação

Instruções por linguagem, ordenadas por volume de requisições. Comece pela linguagem que sua aplicação utiliza.

Java (HttpURLConnection / Apache HttpClient)

Atenção

Esta seção cobre mais de 53% de todas as requisições às APIs Itaú.

Importação no truststore da JVM (keytool)

bash

keytool -importcert -alias itau-root-ca-nova \
  -file root-ca.crt \
  -keystore "$JAVA_HOME/lib/security/cacerts" \
  -storepass changeit -noprompt
keytool -importcert -alias itau-intermediate-nova \
  -file intermediate-ca.crt \
  -keystore "$JAVA_HOME/lib/security/cacerts" \
  -storepass changeit -noprompt

Nota

A senha padrão do cacerts é changeit. Repita para cada instalação do Java (8, 11, 17, 21).

Truststore customizado via propriedades do sistema

bash

java \
  -Djavax.net.ssl.trustStore=/caminho/meu-truststore.jks \
  -Djavax.net.ssl.trustStorePassword=minhaSenha \
  -jar minha-aplicacao.jar

Verificação

bash

keytool -list -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit | grep -i itau

Erros comuns em Java

Erro	Causa	Solução
`PKIX path building failed`	Nova Root CA ausente no truststore.	Importe via `keytool -importcert`.
`handshake_failure`	Protocolo TLS incompatível ou intermediário ausente.	Importe o intermediário e use `-Dhttps.protocols=TLSv1.2`.
`Keystore was tampered with, or password was incorrect`	Senha incorreta do cacerts.	Use `changeit` ou a senha definida pela equipe.

Go usa o trust store do SO por padrão. Para tls.Config customizado ou containers scratch/distroless, carregue programaticamente.

rootCAs, _ := x509.SystemCertPool()
if rootCAs == nil { rootCAs = x509.NewCertPool() }
rootPEM, _ := os.ReadFile("certs/root-ca.crt")
rootCAs.AppendCertsFromPEM(rootPEM)
intPEM, _ := os.ReadFile("certs/intermediate-ca.crt")
rootCAs.AppendCertsFromPEM(intPEM)
tlsConfig := &tls.Config{RootCAs: rootCAs, MinVersion: tls.VersionTLS12}
client := &http.Client{Transport: &http.Transport{TLSClientConfig: tlsConfig}}

Erros comuns em Go

Erro	Causa	Solução
`x509: certificate signed by unknown authority`	Nova Root CA ausente no pool.	Instale no SO ou use `AppendCertsFromPEM`.
`x509: certificate has expired or is not yet valid`	Certificado expirado ou relógio incorreto.	Importe os novos certificados e sincronize o relógio.
`net/http: TLS handshake timeout`	Firewall/proxy bloqueando 443.	Verifique regras de rede.

JavaScript / Node.js

Via NODE_EXTRA_CA_CERTS (sem alterar código)

bash

cat root-ca.crt intermediate-ca.crt > itau-ca-bundle.pem
NODE_EXTRA_CA_CERTS=./itau-ca-bundle.pem node app.js

Programático via https.Agent

javascript

const https = require('node:https');
const tls = require('node:tls');
const fs = require('node:fs');
const rootCA = fs.readFileSync('certs/root-ca.crt');
const intCA = fs.readFileSync('certs/intermediate-ca.crt');
const agent = new https.Agent({ ca: [...tls.rootCertificates, rootCA, intCA] });

Nunca em produção

NUNCA utilize NODE_TLS_REJECT_UNAUTHORIZED=0 em produção — isso desativa toda a verificação de certificados e expõe a aplicação a ataques man-in-the-middle.

Erros comuns em Node.js

Erro	Causa	Solução
`UNABLE_TO_VERIFY_LEAF_SIGNATURE`	Intermediário ausente no bundle.	Adicione o intermediário via `NODE_EXTRA_CA_CERTS` ou `ca`.
`CERT_HAS_EXPIRED`	Certificado da cadeia antiga expirou.	Atualize para os novos certificados.
`SELF_SIGNED_CERT_IN_CHAIN`	Autoassinado na cadeia (proxy corporativo).	Verifique os arquivos e proxies MITM.

Python (requests / urllib3)

Variáveis de ambiente

bash

export REQUESTS_CA_BUNDLE=/caminho/itau-ca-bundle.pem
export SSL_CERT_FILE=/caminho/itau-ca-bundle.pem
python app.py

Parâmetro verify

python

import requests
response = requests.get(
    "https://sts.itau.com.br",
    verify="/caminho/itau-ca-bundle.pem",
    timeout=10
)
print(response.status_code)

Erros comuns em Python

Erro	Causa	Solução
`CERTIFICATE_VERIFY_FAILED`	Nova Root CA ausente no bundle/certifi.	Configure `REQUESTS_CA_BUNDLE` ou `verify=`.
`unable to get local issuer certificate`	Intermediário ausente.	Inclua `intermediate-ca.crt` no bundle PEM.
`WRONG_VERSION_NUMBER`	TLS em porta sem TLS ou proxy incorreto.	Use `https://` e verifique proxies.

Java / Kotlin com OkHttp

OkHttp usa o truststore da JVM por padrão. Atenção especial a CertificatePinner.

Certificate Pinning — atualizar os pins

Adicione os pins (SHA-256) dos novos certificados antes da migração, mantendo os antigos durante a transição.

bash

openssl x509 -in root-ca.crt -pubkey -noout | \
  openssl pkey -pubin -outform DER | \
  openssl dgst -sha256 -binary | base64

Atenção

Mantenha sempre pelo menos dois pins (backup pin) para evitar bloqueios acidentais. Remova os pins antigos só após concluir a migração.

Erros comuns em OkHttp

Erro	Causa	Solução
`Certificate pinning failure!`	Pins não correspondem à nova cadeia.	Adicione os pins SHA-256 dos novos certificados.
`Trust anchor for certification path not found`	Nova Root CA ausente no truststore.	Importe os certificados ou configure `SSLSocketFactory`.
`Chain validation failed`	Cadeia incompleta.	Importe root e intermediário.

C# / .NET

.NET usa o trust store do SO por padrão. Importação programática no Windows:

csharp

using var rootCert = new X509Certificate2("root-ca.crt");
using var rootStore = new X509Store(StoreName.Root, StoreLocation.LocalMachine);
rootStore.Open(OpenFlags.ReadWrite);
rootStore.Add(rootCert);
rootStore.Close();

Erros comuns em C# / .NET

Erro	Causa	Solução
`The remote certificate is invalid`	Nova Root CA ausente no trust store.	Instale no SO ou use `ServerCertificateCustomValidationCallback`.
`The SSL connection could not be established`	Intermediário ausente ou TLS incompatível.	Inclua o intermediário; verifique suporte a TLS 1.2.
`certificate chain could not be built`	Cadeia incompleta.	Importe root e intermediário no trust store.

Delphi / Pascal

A maioria usa Indy. Configure o TIdSSLIOHandlerSocketOpenSSL:

pascal

SSLHandler.SSLOptions.Method := sslvTLSv1_2;
SSLHandler.SSLOptions.RootCertFile := 'certs\itau-ca-bundle.pem';
SSLHandler.SSLOptions.VerifyMode := [sslvrfPeer];

Nota

Os componentes Indy dependem das DLLs do OpenSSL. Garanta que elas estejam acessíveis no PATH ou na pasta da aplicação (32-bit vs 64-bit).

Erros comuns em Delphi

Erro	Causa	Solução
`certificate verify failed`	Root/intermediário ausente no `RootCertFile`.	Aponte para um bundle com root + intermediário.
`Could not load SSL library`	DLLs do OpenSSL ausentes.	Distribua as DLLs compatíveis com a aplicação.
`Socket Error #10054`	TLS incompatível ou firewall.	Use `sslvTLSv1_2` e verifique o firewall.

Ruby

ruby

require 'net/http'
http = Net::HTTP.new('sts.itau.com.br', 443)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_PEER
http.ca_file = 'certs/itau-ca-bundle.pem'

Ou defina globalmente: export SSL_CERT_FILE=/caminho/itau-ca-bundle.pem.

Erros comuns em Ruby

Erro	Causa	Solução
`certificate verify failed (unable to get local issuer certificate)`	Root CA ausente no SO ou `ca_file`.	Instale no SO ou configure `ca_file`.
`certificate has expired`	Certificado antigo expirou.	Atualize para os novos certificados.

PHP

Configuração global via php.ini

ini

openssl.cafile = /caminho/itau-ca-bundle.pem
curl.cainfo = /caminho/itau-ca-bundle.pem

cURL nativo

php

curl_setopt_array($ch, [
    CURLOPT_URL => "https://sts.itau.com.br",
    CURLOPT_CAINFO => "certs/itau-ca-bundle.pem",
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_SSLVERSION => CURL_SSLVERSION_TLSv1_2,
]);

Nunca em produção

Não desabilite a verificação: verify=false (Guzzle) ou CURLOPT_SSL_VERIFYPEER=false.

Erros comuns em PHP

Erro	Causa	Solução
`cURL error 60: unable to get local issuer certificate`	CA não encontrada no bundle.	Configure `curl.cainfo` ou `CURLOPT_CAINFO`.
`cURL error 35: SSL connect error`	TLS incompatível ou intermediário ausente.	Verifique OpenSSL/TLS 1.2 e inclua o intermediário.
`cURL error 51: subject name does not match`	Hostname não confere (proxy MITM).	Verifique a URL e proxies corporativos.

Nota final — aplicável a todas as linguagens

Crie o bundle combinando root-ca.crt e intermediate-ca.crt; mantenha ambas as cadeias durante a transição; valide com curl -v https://sts.itau.com.br; e nunca desabilite a verificação TLS em produção.

Validação e Testes

Antes de considerar a migração concluída, execute uma bateria de testes para garantir que a nova cadeia foi corretamente instalada e que os endpoints estão acessíveis.

Atenção

Execute os testes a partir do mesmo ambiente onde a aplicação roda em produção. Testar de uma máquina local pode mascarar problemas de rede, firewall ou truststore.

Teste via cURL

URL para teste

De acordo com o endereço impactado utilize a respectiva URL de validação:

bash

https://secure.gateway.api.itau/sandbox/ca-validation
https://api.gateway.itau.com.br/sandbox/ca-validation
https://api-bin.gateway.itau.com.br/sandbox/ca-validation

Teste cURL

Antes de realizar a validação, gere um token de acesso utilizando suas credenciais de aplicação:

bash

curl --request POST \
  --url https://sts.itau.com.br/api/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'client_id=<client-id>' \
  --data 'client_secret=<client-secret>'

Após obter o token e garantir que a nova cadeia de certificados foi importada corretamente, execute a chamada abaixo para validar a comunicação com o ambiente:

bash

curl --request GET \
  --url <url-de-validacao-utilizada>'\
  --header 'x-itau-apikey: <client-id>' \
  --header 'x-itau-client-cert: <certificate>' \
  --header 'x-itau-correlationID: 123' \
  --header 'x-itau-flowID: 123'

Teste via OpenSSL

bash

openssl s_client -connect sts.itau.com.br:443 -showcerts

O retorno Verify return code: 0 (ok) confirma que a cadeia completa é confiável.

Códigos de erro comuns do OpenSSL

Código	Descrição	Ação
2	`unable to get issuer certificate`	Root CA ausente no truststore.
20	`unable to get local issuer certificate`	Intermediário ausente.
21	`unable to verify the first certificate`	Cadeia incompleta (servidor não enviou o intermediário).
10	`certificate has expired`	Certificado expirado.
9	`certificate is not yet valid`	Data do sistema incorreta.
19	`self-signed certificate in chain`	CA não reconhecida.

Teste via PowerShell (Windows)

powershell

$endpoints = @(
    "https://secure.gateway.api.itau/healthcheckbalance",
    "https://api.gateway.itau.com.br/healthcheckbalance",
    "https://api-bin.gateway.itau.com.br/healthcheckbalance",
    "https://sts.itau.com.br"
)
foreach ($url in $endpoints) {
    try {
        $r = Invoke-WebRequest -Uri $url -UseBasicParsing -TimeoutSec 30
        Write-Host "[OK]    $url - HTTP $($r.StatusCode)" -ForegroundColor Green
    } catch {
        Write-Host "[FALHA] $url - $($_.Exception.Message)" -ForegroundColor Red
    }
}

Teste de conectividade de rede

Resolução DNS

bash

dig sts.itau.com.br +short
dig secure.gateway.api.itau +short

Conectividade de porta (TCP 443)

bash

nc -zv sts.itau.com.br 443
nc -zv secure.gateway.api.itau 443

Nota

Se os novos hostnames não resolverem, limpe o cache DNS: ipconfig /flushdns (Windows) ou sudo systemd-resolve --flush-caches (Linux).

Checklist de validação

Antes da migração

Nova cadeia (Root CA + Intermediate CA) obtida do Developer Portal;
Certificados verificados com openssl x509 -noout -text -in <arquivo>.pem;
Truststore atualizado com os novos certificados;
Backup do truststore anterior realizado;
Firewall atualizado para 3.44.192.200/29 e 18.96.65.56/29;
Resolução DNS funcional para os novos hostnames;
URLs dos endpoints atualizadas na aplicação;
Certificate pinning atualizado (se aplicável);
Plano de rollback documentado.

Durante a migração

curl -v https://sts.itau.com.br retorna handshake TLS bem-sucedido;
openssl s_client exibe Verify return code: 0 (ok);
Healthchecks dos três endpoints retornam HTTP 200;
Nenhum erro de TLS nos logs da aplicação;
Teste de integração end-to-end executado com sucesso.

Depois da migração

Monitoramento de erros TLS/SSL ativado em produção;
Métricas de latência e erro estáveis por pelo menos 24 horas;
Alertas de expiração futura de certificados configurados;
Endpoints antigos removidos quando descontinuados pelo Itaú;
Documentação interna atualizada;
Equipe comunicada sobre a conclusão.

Troubleshooting — Erros comuns e soluções

Esta seção consolida os erros mais frequentes durante a atualização, com causas prováveis e soluções.

Tabela geral de erros

Erro	Linguagem / Ambiente	Causa provável	Solução
`CERTIFICATE_VERIFY_FAILED`	Python	Intermediário ou Root CA ausente no bundle.	Atualize `certifi` ou use `REQUESTS_CA_BUNDLE`.
`PKIX path building failed`	Java	Truststore da JVM sem a nova cadeia.	Importe via `keytool` (senha `changeit`) e reinicie.
`unable to get local issuer certificate`	OpenSSL / cURL	Diretório de CAs do SO sem a Root CA.	Copie o certificado e rode `update-ca-certificates`/`update-ca-trust`.
`UNABLE_TO_VERIFY_LEAF_SIGNATURE`	Node.js	Não consegue construir a cadeia até uma Root confiável.	Configure `NODE_EXTRA_CA_CERTS`. Nunca use `NODE_TLS_REJECT_UNAUTHORIZED=0`.
`SEC_E_CERT_UNKNOWN`	Windows / .NET	Raiz não instalada no Certificate Store.	Use `Import-Certificate` em `Root` e `CA`.
`handshake_failure`	Java	Protocolo TLS ou cipher incompatível.	Java 8u261+; force `-Dhttps.protocols=TLSv1.2,TLSv1.3`.
`Connection refused / timed out`	Qualquer (rede)	Firewall bloqueando os novos IPs.	Libere `3.44.192.200/29` e `18.96.65.56/29` na 443.
`certificate has expired`	Qualquer	Endpoint antigo ou relógio incorreto.	Migre para o novo endpoint e sincronize via NTP.
`certificate pinning failure`	Mobile / OkHttp	Hash SHA-256 mudou com a renovação.	Atualize os pins; considere pinnar na Root CA.
`DNS resolution failed`	Qualquer (DNS)	Novos hostnames não resolvem.	Limpe o cache DNS e verifique com `nslookup`.
`Trust anchor for certification path not found`	Android / Kotlin	Dispositivo sem a nova Root CA.	Use Network Security Config.
`ERR_CERT_AUTHORITY_INVALID`	Navegadores	Proxy interceptando ou Root não reconhecida.	Instale a Root CA no trust store do SO.

Atenção

Soluções como NODE_TLS_REJECT_UNAUTHORIZED=0, verify=False ou SSLContext sem validação desabilitam completamente a verificação e nunca devem ser usadas em produção.