Primeiros passos

Antes de chamar a RealityConnect API, confirme que sua rede consegue alcançá-la, entenda como o acesso é aplicado e escolha o fluxo OAuth que corresponde à sua integração. Cada fluxo tem seu próprio guia passo a passo.

Pré-requisitos

Você vai precisar de acesso de administrador da organização para criar seu primeiro aplicativo OAuth. Se você ainda não tiver esse acesso, o administrador da sua organização pode concedê-lo ou criar o aplicativo para você.

URLs da API e acesso de rede

Antes de criar as credenciais OAuth, confirme que a máquina ou o servidor que executa sua integração consegue alcançar a API da Prevu3D por HTTPS. Firewalls corporativos, proxies e listas de permissões costumam bloquear o tráfego de saída e causar tempos limite de conexão ou erros de DNS.

Sua integração precisa conseguir alcançar:

Descoberta de OAuth e API: https://cloud-api.prevu3d.com
RealityConnect API regional (sua organização usa uma região; o guia do seu fluxo explica como descobrir a URL exata):

Peça à sua equipe de TI para liberar o acesso HTTPS de saída a esses hosts caso você não consiga se conectar.

Modelo de segurança

O acesso à API é aplicado por meio de três camadas. Uma requisição precisa passar por todas elas para ser bem-sucedida; se qualquer camada negar o acesso, a requisição é recusada.

Camada 1 — Escopos OAuth. Configurados no aplicativo OAuth. Os escopos definem quais famílias de operações o aplicativo tem permissão de executar (por exemplo, read:basic, read:hierarchy).

Camada 2 — Acesso ao conteúdo. Configurado na conta que chama a API. Para o Client Credentials, é o usuário de serviço criado com seu aplicativo OAuth. Para o fluxo do aplicativo nativo, é o usuário conectado. Essa camada determina quais nós (organizações, divisões, sites etc.) o chamador pode ver e sobre os quais pode agir.

Camada 3 — Acesso por função/permissão. Configurado nessa mesma conta, por nó. Determina o que o chamador pode fazer com aquele conteúdo (ler, editar, gerenciar etc.).

Cada guia de fluxo mostra onde e como configurar essas camadas para o seu caso de uso.

Escolha um fluxo OAuth

Escolha o fluxo OAuth que corresponde à forma como sua integração é executada e siga o guia dedicado a ele:

Fluxo	Ideal para	Guia
Client Credentials	Integrações servidor a servidor, scripts e serviços de back-end que agem em nome da sua organização	Fluxo Client Credentials
Aplicativo nativo	Integrações em que o usuário faz login pelo navegador (aplicativos de desktop, ferramentas de CLI, plugins). Usa Authorization Code + Native Application com PKCE, um redirecionamento localhost e nenhum segredo de cliente.	Fluxo de aplicativo nativo
Authorization Code + redirecionamento HTTPS personalizado	Aplicativos web com uma URL de callback no seu próprio domínio	Fluxo Authorization Code + redirecionamento personalizado

Não sabe por onde começar? O Client Credentials é o caminho mais simples para testar a API ou criar automação no lado do servidor. Use o fluxo de aplicativo nativo quando as chamadas à API precisarem ser executadas como um usuário conectado específico.

Licenciamento

Chamar endpoints relacionados ao RealityTwin consome uma licença do RealityTwin Data Manager do pool de licenças flutuantes da sua organização. Consulte Licença do RealityTwin para saber como o pool de licenças funciona e como o uso é contabilizado.

Se sua organização não tiver licenças disponíveis, as chamadas de API relacionadas ao RealityTwin falharão até que uma licença seja liberada ou licenças adicionais sejam adicionadas.

Endpoints experimentais

Algumas operações na referência da API são marcadas como experimentais.

Trate os endpoints experimentais de forma diferente dos estáveis:

Espere mudanças. Caminhos, parâmetros, payloads, respostas, erros ou disponibilidade podem mudar sem as mesmas garantias de estabilidade do restante da API.
Isole o uso. Na sua integração, dê preferência a operações estáveis. Se você depender de algo experimental, mantenha-o atrás de um pequeno adaptador para poder se ajustar rapidamente quando o contrato evoluir.
Mantenha-se atualizado. Acompanhe as notas de versão e revisite a referência da API após as atualizações para não ser surpreendido por mudanças de comportamento.

Próximos passos

Escolha um fluxo entre as opções a seguir e siga o guia dele do início ao fim.

Explore a referência da API para conhecer todas as operações disponíveis.