Requisitos de rede

O uso da RealityConnect API requer acesso HTTPS de saída aos hosts listados abaixo. Esta página cobre todo o caminho de rede: o que precisa estar acessível, como proxies e inspeção TLS afetam as conexões, e como diferenciar um problema de rede de um problema de autenticação.

Resumo dos requisitos

Somente saída, via HTTPS (porta 443). Nenhuma porta de entrada, regra de firewall ou NAT é necessária. Veja Acesso de entrada.
Permita HTTPS de saída para os hostnames abaixo.
Um proxy de saída (forward proxy) corporativo padrão funciona de forma transparente, inclusive um que exija autenticação. Veja Proxies de saída.
Um proxy de inspeção TLS interromperá as conexões, a menos que seu certificado raiz seja confiável para o ambiente de execução da integração. Veja Proxies de inspeção TLS.

Acesso de entrada

Nada precisa ser aberto de entrada para usar a RealityConnect API. Sua integração sempre inicia a conexão de saída em direção à Prevu3D; a Prevu3D nunca abre uma conexão de volta para dentro da sua rede. Não há webhook, URL de callback ou listener para registrar, nem regra de firewall de entrada para criar.

Acesso de saída

Sua integração precisa conseguir acessar três tipos de hosts via HTTPS de saída:

OAuth e descoberta da API: https://cloud-api.prevu3d.com
Seu host regional da RealityConnect API (exatamente um entre):
- https://api-ue1.prevu3d.com
- https://api-ec1.prevu3d.com
- https://api-an1.prevu3d.com
- https://api-cc1.prevu3d.com
Transferências de arquivos: https://cdn.prevu3d.com (downloads) e Amazon S3, *.amazonaws.com (URLs de upload pré-assinadas)

Qual é a minha região?

Sua organização é provisionada em exatamente uma região, portanto você não precisa permitir os quatro hostnames. Em vez de adivinhar ou perguntar ao suporte, faça sua integração chamar o endpoint de descoberta (GET /oauth/api-info, descrito em cada guia de fluxo OAuth) assim que tiver um token: o campo apiUrl da resposta indica qual host regional sua organização realmente usa. Permita apenas esse hostname; você pode ignorar os outros três.

Proxies de saída

A RealityConnect API é uma API HTTPS/JSON padrão. Ela não exige nada incomum do caminho de rede, e não faz nada (como pinning de certificado) que impeça seu funcionamento por meio de um proxy de saída corporativo padrão.

Se sua integração realmente usa seu proxy depende da biblioteca de cliente HTTP na qual ela é construída, não da RealityConnect API:

A maioria dos clientes HTTP (curl, requests do Python, undici/fetch do Node, HttpClient do .NET etc.) respeita as variáveis de ambiente padrão HTTPS_PROXY / HTTP_PROXY, ou uma configuração de proxy equivalente na configuração do cliente. Consulte a documentação da sua biblioteca de cliente para confirmar.
Proxies autenticados (que exigem usuário e senha) também são tratados na camada do cliente HTTP, usando o mesmo mecanismo de credenciais de proxy que o cliente já suporta para qualquer outro destino HTTPS. A RealityConnect API não tem nenhum requisito especial aqui. Se seu cliente já consegue acessar outros serviços HTTPS por meio do seu proxy autenticado, ele consegue acessar a RealityConnect API da mesma forma.

Proxies de inspeção TLS

Algumas redes corporativas executam um proxy de inspeção TLS (descriptografia SSL): ele fica no meio da conexão, apresenta seu próprio certificado à sua integração no lugar do certificado da Prevu3D, e recriptografa o tráfego até o destino real. Essa é uma causa conhecida de falhas de conexão em integrações de API em geral, incluindo a RealityConnect API.

Como isso se manifesta: em vez de uma resposta normal, a chamada HTTPS da sua integração falha durante o handshake TLS com um erro de validação de certificado. A mensagem exata depende do seu cliente HTTP e sistema operacional, mas costuma se parecer com “unable to verify the first certificate”, “certificate verify failed”, “unknown certificate authority”, ou simplesmente uma reinicialização de conexão sem nenhum código de status HTTP (porque a requisição nunca chegou longe o suficiente para receber uma resposta).

O que isso significa: o ambiente de execução da sua integração não reconhece o certificado apresentado pelo proxy de inspeção, porque não confia na autoridade certificadora (CA) interna que esse proxy usa para reassinar o tráfego.

Correção necessária, uma das duas opções:

Adicione a CA raiz corporativa ao trust store realmente usado pela integração. Essa é a solução mais comum, e a etapa mais frequentemente esquecida: muitos ambientes de execução (Java, Node, Python) incluem ou carregam seu próprio conjunto de CAs em vez de usar o do sistema operacional. Instalar a CA raiz corporativa no repositório de certificados do Windows não cobre esses ambientes automaticamente. Verifique se sua linguagem/ambiente de execução precisa de configuração própria (por exemplo, uma variável de ambiente NODE_EXTRA_CA_CERTS, uma flag de JVM -Djavax.net.ssl.trustStore, ou adicionar o certificado ao conjunto usado pela sua instalação do requests/certifi em Python).
Isente os hostnames da RealityConnect API da inspeção TLS, caso seu proxy suporte regras de exceção por destino. Isso costuma ser mais simples do que corrigir o trust store de cada ambiente de execução individualmente.

A opção correta depende do fabricante do proxy e do ambiente de execução da integração.

Diagnóstico: é a rede ou é a autenticação?

Percorra estas quatro verificações em ordem. Cada uma isola uma camada diferente, para que você descubra onde o problema realmente está, em vez de depurar código de autenticação para um problema de rede (ou o contrário).

1. DNS

Confirme se o hostname é resolvido:

nslookup api-ue1.prevu3d.com

(Substitua por cloud-api.prevu3d.com ou pelo host regional da sua organização, conforme necessário.) Se isso falhar ou expirar, o problema está na resolução DNS. Verifique a configuração de DNS da máquina antes de continuar.

2. Handshake TLS

Confirme que uma conexão segura pode ser estabelecida com o host, independentemente de qualquer requisição específica da Prevu3D:

curl -v https://cloud-api.prevu3d.com

Procure por SSL certificate problem, unable to get local issuer certificate, ou uma conexão que é reiniciada antes de qualquer resposta HTTP. Tudo isso aponta para um problema de proxy ou firewall no caminho de rede (veja Proxies de inspeção TLS acima), não para algo no código da sua integração. Uma resposta com um código de status HTTP, mesmo um erro como 401, significa que o TLS teve sucesso e o problema está mais acima na pilha.

O curl incluído no Windows usa o repositório de certificados do Windows, portanto esta verificação pode ter sucesso mesmo quando um ambiente de execução com seu próprio pacote de CAs (Node, Python, Java) continua falhando atrás de um proxy de inspeção TLS. Se a verificação tiver sucesso, mas sua integração apresentar um erro de certificado, consulte Proxies de inspeção TLS.

3. Requisição de token

Confirme que você consegue obter um token de acesso OAuth. Isso verifica se suas credenciais e sua requisição OAuth estão bem formadas, independentemente de qualquer chamada à RealityConnect API:

curl -v -X POST https://cloud-api.prevu3d.com/oauth/token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"

Um 403 (secret incorreto) ou 404 (client ID desconhecido) nesse ponto é um problema de credenciais, não um problema de rede, pois o DNS e o TLS já tiveram sucesso para chegar até aqui.

4. Primeira chamada autenticada

Confirme que o token realmente funciona contra a API:

curl -H "Authorization: Bearer <access_token>" https://cloud-api.prevu3d.com/oauth/api-info

Uma resposta JSON bem-sucedida aqui confirma que todo o caminho (DNS, TLS e autenticação) funciona de ponta a ponta. Um 401/403 nesse ponto, depois que a etapa 3 teve sucesso, aponta para um problema de scopes ou permissões, e não para um problema de rede ou de credenciais. (/oauth/api-info requer o scope read:basic.)

Próximos passos

Primeiros passos: pré-requisitos, o modelo de segurança e a escolha de um fluxo OAuth.