Requisitos de red

Usar la RealityConnect API requiere acceso HTTPS saliente a los hosts indicados a continuación. Esta página cubre toda la ruta de red: qué debe ser accesible, cómo afectan los proxies y la inspección TLS a las conexiones, y cómo distinguir un problema de red de un problema de autenticación.

Resumen de requisitos

Solo saliente, por HTTPS (puerto 443). No se requiere ningún puerto entrante, regla de firewall ni NAT. Consulta Acceso entrante.
Permite HTTPS saliente hacia los hostnames indicados a continuación.
Un proxy de salida (forward proxy) corporativo estándar funciona de forma transparente, incluso si requiere autenticación. Consulta Proxies de salida.
Un proxy de inspección TLS interrumpirá las conexiones, a menos que su certificado raíz sea de confianza para el entorno de ejecución de la integración. Consulta Proxies de inspección TLS.

Acceso entrante

No es necesario abrir nada de forma entrante para usar la RealityConnect API. Tu integración siempre inicia la conexión de forma saliente hacia Prevu3D; Prevu3D nunca abre una conexión de vuelta hacia tu red. No hay ningún webhook, URL de callback ni listener que registrar, ni ninguna regla de firewall entrante que crear.

Acceso saliente

Tu integración debe poder alcanzar tres tipos de hosts por HTTPS saliente:

OAuth y descubrimiento de la API: https://cloud-api.prevu3d.com
Tu host regional de la RealityConnect API (exactamente uno de):
- https://api-ue1.prevu3d.com
- https://api-ec1.prevu3d.com
- https://api-an1.prevu3d.com
- https://api-cc1.prevu3d.com
Transferencias de archivos: https://cdn.prevu3d.com (descargas) y Amazon S3, *.amazonaws.com (URLs de carga prefirmadas)

¿Cuál es mi región?

Tu organización está aprovisionada en exactamente una región, así que no necesitas permitir los cuatro hostnames. En lugar de adivinar o preguntar al soporte, haz que tu integración llame al endpoint de descubrimiento (GET /oauth/api-info, descrito en cada guía de flujo OAuth) una vez que tengas un token: el campo apiUrl de la respuesta indica qué host regional usa realmente tu organización. Permite ese único hostname; puedes omitir los otros tres.

Proxies de salida

La RealityConnect API es una API HTTPS/JSON estándar. No exige nada inusual de la ruta de red, y no hace nada (como el pinning de certificados) que impida su funcionamiento a través de un proxy de salida corporativo estándar.

Que tu integración use realmente tu proxy depende de la biblioteca de cliente HTTP sobre la que está construida, no de la RealityConnect API:

La mayoría de los clientes HTTP (curl, requests de Python, undici/fetch de Node, HttpClient de .NET, etc.) respetan las variables de entorno estándar HTTPS_PROXY / HTTP_PROXY, o un ajuste de proxy equivalente en la configuración del cliente. Consulta la documentación de tu biblioteca de cliente para confirmarlo.
Los proxies autenticados (que requieren usuario y contraseña) también se gestionan a nivel del cliente HTTP, mediante el mismo mecanismo de credenciales de proxy que el cliente ya admite para cualquier otro destino HTTPS. La RealityConnect API no tiene ningún requisito especial aquí. Si tu cliente ya puede alcanzar otros servicios HTTPS a través de tu proxy autenticado, puede alcanzar la RealityConnect API de la misma manera.

Proxies de inspección TLS

Algunas redes corporativas ejecutan un proxy de inspección TLS (descifrado SSL): se sitúa en medio de la conexión, presenta su propio certificado a tu integración en lugar del de Prevu3D, y vuelve a cifrar el tráfico hacia el destino real. Esta es una causa conocida de fallos de conexión en integraciones de API en general, incluida la RealityConnect API.

Cómo se manifiesta: en lugar de una respuesta normal, la llamada HTTPS de tu integración falla durante el handshake TLS con un error de validación de certificado. El mensaje exacto depende de tu cliente HTTP y sistema operativo, pero suele parecerse a «unable to verify the first certificate», «certificate verify failed», «unknown certificate authority», o simplemente un reinicio de la conexión sin ningún código de estado HTTP (porque la solicitud nunca llegó lo bastante lejos como para recibir una respuesta).

Qué significa esto: el entorno de ejecución de tu integración no reconoce el certificado presentado por el proxy de inspección, porque no confía en la autoridad de certificación (CA) interna que ese proxy usa para volver a firmar el tráfico.

Solución requerida, una de estas dos opciones:

Añade la CA raíz corporativa al almacén de confianza (trust store) que realmente usa la integración. Esta es la solución más común, y el paso que más se pasa por alto: muchos entornos de ejecución (Java, Node, Python) incluyen o cargan su propio paquete de CA en lugar de usar el del sistema operativo. Instalar la CA raíz corporativa en el almacén de certificados de Windows no los cubre automáticamente. Comprueba si tu lenguaje/entorno de ejecución necesita su propia configuración (por ejemplo, una variable de entorno NODE_EXTRA_CA_CERTS, una opción de JVM -Djavax.net.ssl.trustStore, o añadir el certificado al paquete que usa tu instalación de requests/certifi en Python).
Excluye los hostnames de la RealityConnect API de la inspección TLS, si tu proxy admite reglas de exclusión por destino. Esto suele ser más sencillo que corregir el almacén de confianza de cada entorno de ejecución individualmente.

La opción correcta depende del fabricante del proxy y del entorno de ejecución de la integración.

Diagnóstico: ¿es la red o es la autenticación?

Realiza estas cuatro comprobaciones en orden. Cada una aísla una capa distinta, de modo que averigües dónde está realmente el problema en lugar de depurar código de autenticación para un problema de red (o al revés).

1. DNS

Confirma que el hostname se resuelve:

nslookup api-ue1.prevu3d.com

(Sustitúyelo por cloud-api.prevu3d.com o el host regional de tu organización según corresponda.) Si esto falla o expira, el problema está en la resolución DNS. Revisa la configuración DNS de la máquina antes de continuar.

2. Handshake TLS

Confirma que se puede establecer una conexión segura con el host, independientemente de cualquier solicitud específica de Prevu3D:

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

Busca SSL certificate problem, unable to get local issuer certificate, o una conexión que se reinicia antes de recibir cualquier respuesta HTTP. Todo esto apunta a un problema de proxy o firewall en la ruta de red (consulta Proxies de inspección TLS más arriba), no a algo en el código de tu integración. Una respuesta con un código de estado HTTP, incluso un error como 401, significa que el TLS se completó correctamente y que el problema está más arriba en la pila.

El curl incluido en Windows usa el almacén de certificados de Windows, por lo que esta comprobación puede tener éxito aunque un entorno de ejecución con su propio paquete de CA (Node, Python, Java) siga fallando detrás de un proxy de inspección TLS. Si la comprobación tiene éxito pero tu integración muestra un error de certificado, consulta Proxies de inspección TLS.

3. Solicitud de token

Confirma que puedes obtener un token de acceso OAuth. Esto verifica que tus credenciales y tu solicitud OAuth están bien formadas, independientemente de cualquier llamada a la RealityConnect API:

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

Un 403 (secret incorrecto) o 404 (client ID desconocido) en este punto es un problema de credenciales, no un problema de red, ya que el DNS y el TLS ya se completaron con éxito para llegar hasta aquí.

4. Primera llamada autenticada

Confirma que el token realmente funciona contra la API:

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

Una respuesta JSON exitosa aquí confirma que toda la ruta (DNS, TLS y autenticación) funciona de extremo a extremo. Un 401/403 en este punto, después de que el paso 3 tuvo éxito, apunta a un problema de scopes o permisos en lugar de a un problema de red o de credenciales. (/oauth/api-info requiere el scope read:basic.)

¿Qué sigue?

Primeros pasos: requisitos previos, el modelo de seguridad y la elección de un flujo OAuth.