Integrazioni Private: tutto quello che devi sapere

Integrazioni Private: tutto quello che devi sapere

Cosa sono le Integrazioni Private?

Le Integrazioni Private permettono di creare potenti integrazioni personalizzate tra il tuo account Squadd/GoHighLevel e qualsiasi altra applicazione di terze parti.

Se vuoi integrare il tuo account HighLevel con un'applicazione esterna hai due possibilità:

• Cercare e installare un'applicazione compatibile dall'App Marketplace.

• Creare autonomamente un'integrazione privata, oppure farla sviluppare da uno sviluppatore utilizzando le API.

Le Integrazioni Private ti permettono di realizzare la seconda opzione in modo sicuro.

I principali vantaggi sono:

• Semplicità: puoi generare i token delle Integrazioni Private direttamente dalle impostazioni del tuo account e gestirli facilmente.

• Sicurezza: puoi limitare gli scope e i permessi a cui uno sviluppatore può accedere all'interno del tuo account.

Qual è la differenza tra Integrazioni Private e API Key?

In parole semplici, le Integrazioni Private rappresentano un'alternativa alle API Key più potente e più sicura.

Perché i Private Integration Token sono consigliati per le nuove credenziali

I Private Integration Token, o PIT, sono il sostituto consigliato delle vecchie API Key perché permettono una gestione degli accessi più sicura e flessibile.

Le vecchie API Key che rimangono inutilizzate per più di 90 giorni possono essere contrassegnate come Expired, cioè scadute, nelle impostazioni.

Dal momento che non è più possibile creare nuove API Key legacy v1, per tutte le nuove credenziali o per la migrazione di vecchie integrazioni è consigliato utilizzare i PIT.

Se utilizzi ancora una vecchia API Key, Squadd/GoHighLevel consiglia di migrare l'integrazione verso un Private Integration Token quando possibile.

Qual è la differenza tra Integrazioni Private e OAuth2 Access Token?

In parole semplici, le Integrazioni Private possono essere considerate degli OAuth2 Access Token statici o fissi.

Come si utilizzano le Integrazioni Private?

I token delle Integrazioni Private vengono utilizzati nell'header Authorization, esattamente come gli altri Access Token.

Per esempio, per ottenere i dettagli di una Location puoi utilizzare la Get Sub-account API inserendo il Private Integration Token dell'Agency nell'header Authorization.

curl --request GET \
  --url https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT \
  --header 'Accept: application/json' \
  --header 'Authorization: <IL_TUO_PRIVATE_INTEGRATION_TOKEN>' \
  --header 'Version: 2021-07-28'

Testare un'Integrazione Privata tramite chiamate API

Dopo aver creato un'Integrazione Privata potresti volerla testare inviando dei dati a un endpoint API.

Per farlo avrai bisogno dell'URL corretto dell'endpoint API.

Ecco un esempio per testare l'integrazione creando un nuovo contatto:

curl --request POST \
  --url https://services.leadconnectorhq.com/contacts/ \
  --header 'Authorization: <IL_TUO_PRIVATE_INTEGRATION_TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'Version: 2021-07-28' \
  --data '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "locationId": "LOCATION_ID"
  }'

Assicurati di:

• Sostituire LOCATION_ID con l'ID reale del Sub-Account.

• Sostituire il valore dell'header Authorization con il Private Integration Token generato.

Per l'elenco completo degli endpoint disponibili e delle funzionalità di test puoi consultare la documentazione ufficiale:

https://developers.gohighlevel.com

Come si gestiscono le Integrazioni Private?

Chi può creare Integrazioni Private?

Di default tutti gli Agency Admin possono creare e gestire Integrazioni Private.

Puoi però limitare questo permesso a livello di singolo utente.

Vai su: Settings > Team > Modifica Admin > Roles & Permissions

Da qui puoi abilitare o disabilitare i permessi relativi alle Private Integrations.

Dove si trovano le Integrazioni Private?

Puoi trovare le Integrazioni Private all'interno delle impostazioni del tuo subaccount.

Se non trovi questa voce nelle impostazioni, verifica di aver abilitato la funzione all'interno di Labs.

Come si crea una nuova Integrazione Privata?

Passaggio 1

Clicca su: Create new Integration

Passaggio 2

Assegna un nome e una descrizione alla tua Integrazione Privata.

Questo aiuterà te e il tuo team a capire facilmente a cosa serve.

Passaggio 3

Seleziona gli scope e i permessi a cui vuoi consentire l'accesso tramite l'Integrazione Privata all'interno del tuo subaccount.

Per una maggiore sicurezza dei dati è consigliato selezionare solamente gli scope realmente necessari.

Passaggio 4

Copia il token generato e condividilo con lo sviluppatore dell'applicazione di terze parti.

Assicurati di condividere il token solamente con persone o aziende di cui ti fidi.

Non condividere mai pubblicamente il token.

Quali sono le best practice per proteggere il Private Integration Token?

Squadd/GoHighLevel consiglia di ruotare i Private Integration Token ogni 90 giorni.

Ecco come fare.

Passaggio 1

Vai su Private Integrations all'interno delle impostazioni.

Clicca sull'Integrazione Privata che hai creato.

Passaggio 2

Clicca su: Rotate and expire this token later

Passaggio 3

Quando compare il messaggio di avviso, clicca su Continue se sei sicuro di voler procedere con la rotazione.

Passaggio 4

Copia il nuovo token e aggiornalo all'interno dell'applicazione di terze parti.

Avrai una finestra di 7 giorni durante la quale continueranno a funzionare sia il vecchio sia il nuovo token.

Al termine dei 7 giorni il vecchio token scadrà.

Durante questi 7 giorni avrai due opzioni:

• Cancel rotation: puoi annullare la rotazione, per esempio se lo sviluppatore ha bisogno di più tempo per aggiornare il token nell'applicazione.

• Expire Now: puoi far scadere immediatamente il vecchio token, per esempio se l'applicazione è già stata aggiornata con il nuovo token.

Token compromesso?

Se pensi che il token sia stato compromesso, puoi invalidarlo immediatamente.

Passaggio 1

Vai su Private Integrations nelle impostazioni e clicca sull'Integrazione Privata interessata.

Passaggio 2

Clicca su: Rotate and expire this token now

Passaggio 3

Quando compare l'avviso clicca su Continue, se sei sicuro di voler procedere.

Passaggio 4

Copia il nuovo token e aggiornalo nell'applicazione di terze parti.

Posso modificare i permessi dell'Integrazione Privata senza aggiornare il token?

Sì.

Puoi modificare in qualsiasi momento:

• Nome dell'Integrazione Privata

• Descrizione

• Scope

• Permessi

senza dover generare un nuovo token.

Ecco come fare.

Passaggio 1

Vai su Private Integrations nelle impostazioni.

Dal menu con i tre puntini seleziona: Edit

Passaggio 2

Modifica, se necessario, il nome e la descrizione dell'Integrazione Privata.

Clicca quindi su: Next

Passaggio 3

Modifica gli scope e i permessi a cui l'Integrazione Privata deve avere accesso.

Per una maggiore sicurezza dei dati è consigliato mantenere attivi solamente gli scope realmente necessari.

Clicca su Update per salvare le modifiche.

Gli utenti possono creare fino a 20 Private Integration Token sia a livello Agency sia a livello Location.

Come elimino un'Integrazione Privata quando non mi serve più?

Puoi eliminare un'Integrazione Privata quando non utilizzi più l'applicazione di terze parti associata.

Vai su: Settings > Private Integrations

Apri il menu con i tre puntini relativo all'integrazione interessata e seleziona: Delete

In questo modo l'Integrazione Privata verrà eliminata e il relativo accesso verrà revocato.