HubSpot

Connessione di HubSpot con Siesta AI

1. In Connessioni seleziona Aggiungi Connessione e scegli HubSpot.

2. Inserisci il Private App token (chiave API) e imposta Condiviso o Privato.

3. In HubSpot apri Impostazioni -> Integrazioni -> App Private e crea una nuova applicazione.

4. Completa le informazioni di base dell'applicazione.

5. Imposta gli scopes necessari per gli oggetti CRM.

6. Nella scheda Auth copia il Token di Accesso e usalo in Siesta AI.

Panoramica

Questa Connessione fornisce un'interfaccia standardizzata per lavorare con HubSpot CRM. Consente la creazione e la lettura delle entità CRM di base: Aziende, Contatti, Affari e Pipeline.

L'integrazione è progettata come stateless, deterministica e fail-fast, adatta per:

• Automazione CRM
• Sincronizzazione dei lead
• Orchestrazione della pipeline di vendita e ricavi
• Flussi di lavoro aziendali auditabili

Autenticazione e Sicurezza

• La connessione comunica esclusivamente tramite l'API ufficiale di HubSpot.
• L'autenticazione è gestita a livello di account HubSpot (OAuth / Private App token).
• Nessun dato sensibile viene registrato o memorizzato nella cache.
• Tutte le operazioni vengono eseguite con le autorizzazioni assegnate in HubSpot.

I diritti di accesso (scopes) influenzano direttamente la disponibilità delle operazioni. Uno scope errato significa errore.

Entità Supportate

• Azienda
• Contatto
• Affare
• Pipeline

Ogni operazione lavora con gli ID interni di HubSpot, non con i nomi.

1. Operazioni Azienda

1.1 CreaAzienda

Descrizione
Crea una nuova azienda in HubSpot CRM.

Parametri di ingresso

Parametro	Tipo	Obbligatorio	Descrizione
name	String	Sì	Nome dell'azienda.
domain	String	Sì	Dominio dell'azienda (deve essere unico).

Comportamento

• Se il dominio esiste già, l'operazione fallisce.
• Non esegue fuzzy matching né normalizzazione del dominio.

Utilizzo tipico

• Onboarding di nuovi clienti
• Sincronizzazione delle aziende da sistemi esterni

2. Operazioni Contatto

2.1 CreaContatto

Descrizione
Crea un nuovo contatto in HubSpot CRM.

Parametri di ingresso

Parametro	Tipo	Obbligatorio	Descrizione
email	String	Sì	Email del contatto (deve essere unico).
firstName	String	Sì	Nome di battesimo.
lastName	String	Sì	Cognome.

Comportamento

• L'email funge da identificatore unico.
• Email duplicato = errore grave.

2.2 OttieniContattoPerEmail

Descrizione
Restituisce un contatto in base all'indirizzo email.

Parametri di ingresso

Parametro	Tipo	Obbligatorio
email	String	Sì

2.3 OttieniContattoPerId

Descrizione
Restituisce un contatto in base al suo ID unico di HubSpot.

Parametri di ingresso

Parametro	Tipo	Obbligatorio
contactId	Int64	Sì

2.4 OttieniTuttiContatti

Descrizione
Restituisce un elenco di contatti in HubSpot CRM.

Parametri di ingresso

Parametro	Tipo	Obbligatorio	Descrizione
limit	Int	No	Numero massimo di record restituiti.

3. Operazioni Affare

3.1 CreaAffare

Descrizione
Crea un nuovo affare e lo assegna a un contatto specifico.

Parametri di ingresso

Parametro	Tipo	Obbligatorio	Descrizione
dealName	String	Sì	Nome dell'affare.
contactId	String	Sì	ID del Contatto esistente.
pipelineId	Int64	Sì	ID della pipeline (non il nome).
stageId	Int64	Sì	ID della fase (non il nome).
amount	Int	No	Valore dell'affare.

Comportamento

• La pipeline e la fase devono esistere.
• Non esegue mappatura automatica dei nomi sugli ID.
• Relazione errata = errore.

3.2 OttieniAffarePerId

Descrizione
Restituisce i dettagli dell'affare in base all'ID.

Parametri di ingresso

Parametro	Tipo	Obbligatorio
dealId	Int64	Sì

3.3 OttieniTuttiAffari

Descrizione
Restituisce un elenco di affari.

Parametri di ingresso

Parametro	Tipo	Obbligatorio
limit	Int	No

4. Operazioni Pipeline

4.1 ElencaTutteLePipeline

Descrizione
Restituisce tutte le pipeline, comprese le loro fasi e gli ID corrispondenti.

Parametri di ingresso
Nessuno.

Nota Questo passaggio è obbligatorio se non vuoi creare affari alla cieca.

5. Operazioni di Ricerca

5.1 RicercaAziende

Descrizione
Cerca aziende in base al nome.

Parametri di ingresso

Parametro	Tipo	Obbligatorio	Descrizione
name	String	No	Nome dell'azienda (senza dominio).

Limitazioni

• Non utilizzare domini, URL o email.
• La ricerca è testuale, senza fuzzy matching.