Per iniziare

Prima di chiamare la RealityConnect API, verifica che la tua rete possa raggiungerla, comprendi come viene applicato l’accesso e scegli il flusso OAuth adatto alla tua integrazione. Ogni flusso ha la propria guida passo passo.

Prerequisiti

Avrai bisogno dell’accesso come amministratore dell’organizzazione per creare la tua prima applicazione OAuth. Se non lo hai ancora, l’amministratore della tua organizzazione può concederti l’accesso o creare l’applicazione per te.

URL dell’API e accesso di rete

Prima di creare le credenziali OAuth, verifica che la macchina o il server che esegue la tua integrazione possa raggiungere l’API Prevu3D tramite HTTPS. I firewall aziendali, i proxy e le liste di autorizzazione spesso bloccano il traffico in uscita e causano timeout di connessione o errori DNS.

La tua integrazione deve essere in grado di raggiungere:

OAuth e discovery dell’API: https://cloud-api.prevu3d.com
RealityConnect API regionale (la tua organizzazione usa una regione; la guida al flusso spiega come scoprire l’URL esatto):

Chiedi al tuo team IT di consentire l’accesso HTTPS in uscita a questi host se non riesci a connetterti.

Modello di sicurezza

L’accesso all’API viene applicato attraverso tre livelli. Una richiesta deve superarli tutti per avere successo; se un qualsiasi livello nega l’accesso, la richiesta fallisce.

Livello 1 — Scope OAuth. Configurati sull’applicazione OAuth. Gli scope definiscono quali famiglie di operazioni l’applicazione è autorizzata a eseguire (ad esempio read:basic, read:hierarchy).

Livello 2 — Accesso ai contenuti. Configurato sull’account che chiama l’API. Per il Client Credentials, si tratta dell’utente di servizio creato con la tua applicazione OAuth. Per il flusso Native app, è l’utente che ha effettuato l’accesso. Questo livello determina quali nodi (organizzazioni, divisioni, siti, ecc.) il chiamante può vedere e su cui può agire.

Livello 3 — Accesso a ruoli / permessi. Configurato sullo stesso account, per nodo. Determina cosa il chiamante può fare con quel contenuto (lettura, modifica, gestione, ecc.).

Ogni guida al flusso illustra dove e come configurare questi livelli per il tuo caso d’uso.

Scegli un flusso OAuth

Scegli il flusso OAuth adatto al modo in cui viene eseguita la tua integrazione, quindi segui la sua guida dedicata:

Flusso	Ideale per	Guida
Client Credentials	Integrazioni server-to-server, script e servizi di back-end che agiscono per conto della tua organizzazione	Flusso Client Credentials
Native app	Integrazioni in cui un utente accede tramite un browser (app desktop, strumenti CLI, plugin). Usa Authorization Code + Native Application con PKCE, un redirect localhost e nessun client secret.	Flusso Native Application
Authorization Code + redirect HTTPS personalizzato	Applicazioni web con un URL di callback sul tuo dominio	Flusso Authorization Code + redirect personalizzato

Non sai da dove iniziare? Client Credentials è il percorso più semplice per testare l’API o creare automazioni lato server. Usa il flusso Native app quando le chiamate all’API devono essere eseguite come uno specifico utente che ha effettuato l’accesso.

Endpoint sperimentali

Alcune operazioni nel riferimento API sono contrassegnate come sperimentali.

Tratta gli endpoint sperimentali in modo diverso da quelli stabili:

Aspettati modifiche. Percorsi, parametri, payload, risposte, errori o disponibilità possono cambiare senza le stesse garanzie di stabilità del resto dell’API.
Isola l’utilizzo. Nella tua integrazione, preferisci le operazioni stabili. Se ti affidi a qualcosa di sperimentale, tienilo dietro un piccolo adattatore in modo da poterti adattare rapidamente quando il contratto evolve.
Rimani aggiornato. Segui le note di rilascio e rivedi il riferimento API dopo gli aggiornamenti per non essere sorpreso da cambiamenti comportamentali.

Cosa c’è dopo?

Scegli un flusso tra le opzioni seguenti e segui la sua guida dall’inizio alla fine.

Esplora il riferimento API per vedere tutte le operazioni disponibili.