Introducción
La API de RealityConnect es la única superficie pública que permite a los sistemas externos interactuar con el ecosistema de Prevu3D. Úsala para leer y escribir contenido en RealityPlatform, gestionar espacios de trabajo de RealityTwin, administrar tu organización, subir archivos y conjuntos de datos, y mucho más.
Cómo está organizada la API
Sección titulada «Cómo está organizada la API»Merece la pena conocer algunas decisiones de diseño antes de empezar a desarrollar:
- URLs base regionales. La API se ejecuta en varias regiones (US East, EU Central, Asia North, Canada Central). Tu organización está aprovisionada en exactamente una de ellas. Obtén siempre tu URL base desde el endpoint de detección en lugar de codificarla de forma fija. La guía de Primeros pasos muestra cómo hacerlo.
- Todo está delimitado a tu organización. Un token solo ve los nodos a los que se ha concedido acceso al usuario de servicio. No son posibles las llamadas entre organizaciones.
- Los recursos viven en una jerarquía de contenido. La mayoría de las operaciones apuntan a un nodo identificado por un UUID. Los nodos forman un árbol (organización → división → sitio → carpeta → activo) que puedes recorrer con el endpoint
/nodes/{id}/browse. - Control de acceso de tres capas. Los ámbitos de OAuth, el acceso al contenido y los roles por nodo deben superarse para que una solicitud tenga éxito. Consulta el modelo de seguridad para saber cómo configurar cada uno.
- JSON sobre HTTPS. Cada endpoint acepta y devuelve JSON, usa autenticación por token bearer y sigue los códigos de estado HTTP estándar.
Autenticación OAuth
Sección titulada «Autenticación OAuth»La autenticación de la API se basa en el protocolo OAuth2. Flujos admitidos:
| Flujo OAuth | Descripción | Ejemplos de casos de uso |
|---|---|---|
| Client Credentials | Acceso de servidor a servidor sin un usuario con sesión iniciada. Crea un usuario de servicio en tu organización; sus permisos se configuran por separado. | Scripts, automatización, integraciones de backend, pruebas de la API |
| Aplicación nativa | Un usuario inicia sesión a través del navegador y consiente los ámbitos. Usa Authorization Code + Native Application con PKCE y un redireccionamiento a http://localhost. Sin secreto de cliente. | Apps de escritorio, herramientas CLI, plugins de CAD |
| Authorization Code + redireccionamiento HTTPS personalizado | Aplicaciones web con una URL de retorno en tu propio dominio. Usa Authorization Code con PKCE y un URI de redireccionamiento HTTPS de coincidencia exacta. | Apps web, integraciones SaaS |
Próximos pasos
Sección titulada «Próximos pasos»- Primeros pasos: requisitos previos, acceso de red, modelo de seguridad y elección de un flujo OAuth.
- Flujo de Client Credentials: configuración de servidor a servidor desde la creación de la app OAuth hasta tu primera llamada a la API.
- Flujo de aplicación nativa: inicio de sesión del usuario con PKCE y un redireccionamiento a localhost.
- Flujo de Authorization Code + redireccionamiento personalizado: inicio de sesión de app web con PKCE y un retorno HTTPS personalizado en tu dominio.
- Referencia interactiva de la API: catálogo completo de endpoints con esquemas de solicitud/respuesta y un generador de solicitudes integrado.
- Fragmentos de código: ejemplos de Python listos para copiar y pegar para operaciones comunes de la API.
- Flujos de trabajo de Data Bundle: creación de un data bundle, subida de datos, inicio del procesamiento, seguimiento del progreso y descarga de archivos de entrada.