Como adicionar o certificado de uma API de terceiros para testar localmente usando o Keytool

Ao integrar uma API de terceiros em um projeto Java, especialmente durante o desenvolvimento local, é comum encontrar erros relacionados a SSL, como:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException:
PKIX path building failed: unable to find valid certification path to requested target

Esse erro ocorre quando o certificado da API não é reconhecido pela JVM, geralmente porque é um certificado autoassinado ou emitido por uma autoridade que ainda não está no truststore padrão do Java.

Para resolver isso, é necessário importar o certificado no keystore de confiança da JVM, usando a ferramenta keytool.

O que é o Keytool

O keytool é uma ferramenta de linha de comando que faz parte do JDK.

Ele permite gerenciar keystores (repositórios de certificados e chaves) utilizados pela JVM para autenticação SSL/TLS.

Importante:

O keytool já está disponível nativamente tanto no Linux quanto no Git Bash no Windows (desde que o JDK esteja corretamente instalado e configurado no PATH).

Etapas para importar o certificado no ambiente local

1. Obtenha o certificado da API de terceiros

Você pode exportar o certificado diretamente pelo navegador.

No Google Chrome, por exemplo:

1. Acesse a URL da API (por exemplo: https://api.dominio.com)

2. Clique no cadeado ao lado da barra de endereço

3. Selecione "Detalhes do certificado"

4. Escolha um local para salvar com nome "nome-api-cert.cert" e no tipo selecionar "binário codificado por DER, certificado único" e clica no botão Exportar

2. Localize o cacerts da JVM

O arquivo cacerts é o truststore padrão do Java e fica dentro da pasta lib/security da sua instalação do JDK.

Windows com Git Bash: /c/Program Files/Java/jdk-17/lib/security/cacerts

Linux: /usr/lib/jvm/java-17-openjdk/lib/security/cacerts

Dica: se estiver usando o Git Bash, pode navegar até o diretório do JDK usando comandos Linux normalmente.

3. Execute o comando do Keytool para importar

No terminal (Git Bash ou Linux), rode o seguinte comando:

keytool -importcert -trustcacerts -alias api-terceiro -file /caminho/onde/salvou/nome-api-cert.cert -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit

Explicando os parâmetros:

Parâmetro	Descrição
-importcert	Indica que você quer importar um certificado
-trustcacerts	Confirma que é um certificado confiável
-alias	Nome de identificação do certificado dentro do keystore
-file	Caminho do arquivo .cer que será importado
-keystore	Caminho do keystore onde será armazenado (geralmente cacerts)
-storepass	Senha do keystore (padrão do Java é changeit)

Ao ser questionado se deseja confiar no certificado, digite yes e pressione Enter.

3. Validar se o certificado foi importado corretamente

Após a importação, verifique se o certificado está presente no keystore com:

keytool -list -keystore "$JAVA_HOME/lib/security/cacerts" -alias api-terceiro -storepass changeit

Se aparecer o nome do certificado e o emissor (issuer), significa que a importação foi bem-sucedida.

4. Reinicie a aplicação

Depois de importar o certificado, reinicie a aplicação Java ou o servidor (por exemplo, Spring Boot, Quarkus ou Tomcat) para que as alterações entrem em vigor.

Boas práticas

Evite editar diretamente o cacerts da JVM de produção.

O ideal é criar um keystore separado, como custom-truststore.jks, e apontar para ele via propriedades de sistema:

-Djavax.net.ssl.trustStore=/caminho/custom-truststore.jks
-Djavax.net.ssl.trustStorePassword=changeit

Controle de versão:

Nunca coloque certificados ou arquivos .jks diretamente no repositório Git.

Guarde-os em local seguro e documente o procedimento de importação.

Ambiente limpo:

Caso use múltiplas versões do Java, verifique sempre o $JAVA_HOME correto antes de importar o certificado.

Considerações finais

Adicionar o certificado de uma API de terceiros no ambiente local é uma prática comum e necessária quando o SSL não é reconhecido pela JVM.

Usando o keytool, você pode facilmente importar o certificado e eliminar erros de handshake durante o desenvolvimento.

O Git Bash no Windows funciona exatamente como um terminal Linux, e como o keytool é nativo do JDK, o procedimento é o mesmo nos dois sistemas.

Com isso, você garante que sua aplicação consiga se comunicar com segurança com APIs externas, mesmo em ambiente de testes.

Feito!