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.

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.