Solavel Documenti
Italiano

Integrazioni

Ultimo aggiornamento

La scheda Integrazioni del progetto collega un progetto ad altri sistemi:

  • I webhook in uscita inviano gli eventi del progetto (attività creata, sprint avviato, documento creato…) a un endpoint HTTPS di tua proprietà, firmati in modo che il destinatario possa fidarsi di essi.
  • I Token webhook in entrata consentono a un sistema esterno (strumento per moduli, GitHub, script) di creare attività o commenti nel progetto.
  • I token API pubblica concedono a un altro sistema accesso con ambito, in lettura o scrittura, alle attività e al tempo del progetto tramite l'API di SolaProjects.
  • Disponibilità dei provider nativi mostra connessioni già predisposte (Slack, Microsoft Teams, GitHub, GitLab, Google Calendar, Google Drive, OneDrive, Zapier / IFTTT) e se ciascuna può essere collegata.

Usala quando un progetto deve comunicare con un altro strumento, ad esempio pubblicare aggiornamenti delle attività nella dashboard del cliente o trasformare richieste dal sito in attività. La configurano responsabili e amministratori del progetto, di solito una volta per progetto con il referente IT.

Due pagine si chiamano Integrazioni. Questa pagina riguarda la scheda del progetto. La voce Integrazioni nella sezione Area di lavoro della barra laterale (/projects/settings/integrations) è la Connessione SolaCount dell’organizzazione — vedi Connessione SolaCount dell’organizzazione qui sotto e Budget e finanze.

#Dove trovarlo

Barra laterale Sezione Progetto → Integrazioni (tra Automazioni e AI)
URL /projects/{project}/integrations
Tavolozza comandi Integrazioni · {project name} sotto Progetto corrente

Chi lo vede:

  • Piano: le integrazioni sono una funzione del piano Premium (anche Enterprise). Nei piani inferiori la scheda è nascosta. Se un piano a pagamento scade, la scheda scompare e i webhook non vengono più proposti finché non rinnovi.
  • Ruolo: solo chi può modificare il progetto può caricare la scheda (vedi Permessi). Gli altri vedono "Impossibile caricare le integrazioni." con Riprova.

#Tour della schermata

#Scheda di intestazione

Integrazioni — Webhook in uscita, token in entrata e cronologia delle consegne.

Riquadro Significato
In uscita Webhook in uscita attivi.
Token in entrata Token in entrata attivi e non revocati.
Consegne recenti I tentativi di consegna elencati in Consegne recenti.
Consegne fallite Tentativi non riusciti tra questi (in rosso se superiori a zero).

#Scheda dei webhook in uscita

Invia eventi di progetto con POST a un endpoint HTTPS esterno, firmati con HMAC-SHA256. Nuovo webhook è in alto a destra.

Ogni scheda webhook mostra il nome, l’URL dell’endpoint, un badge di stato (Attivo, Disabilitato o Archiviato), un’etichetta per ogni evento sottoscritto e {n} consegne · {n} fallite. Azioni sulla riga (assenti per webhook archiviati): Modifica, Test, Ruota segreto, Archivia.

Stato vuoto: Nessun webhook in uscita — Creane uno per inviare eventi a un sistema esterno.

#Scheda dei token webhook in entrata

Consenti a sistemi esterni di creare attività/commenti tramite POST con un token segreto. Nuovo token in alto a destra.

Ogni scheda token: nome, provider (Personalizzato o GitHub) · ultimo utilizzo {date} o mai utilizzato, indicatoreAttivo, Inattivo o Revocato. Azioni (assenti per token revocati): Ruota, Revoca.

Stato vuoto: Nessun token in entrata — Crea un token per accettare webhook in entrata.

#Scheda API pubblica

Crei token portatore con ambito per gli endpoint documentati di progetti, attività e registrazioni di tempo. Pulsanti: Documentazione (apre il riferimento OpenAPI in una nuova scheda) e Nuovo token.

Ogni scheda token mostra: nome, ultimo utilizzo {date} / mai utilizzato, indicatore di stato e un'etichetta per capacità. Azioni: Rigenera, Revoca.

Stato vuoto: Nessun token API — Crea un token per l'API pubblica.

#Scheda consegne recenti

Tentativi di consegna in uscita e relativo esito. Badge con il conteggio.

Colonna Significato
Quando Data della consegna.
Webhook Nome del webhook, oppure Webhook archiviato.
Evento Tipo di evento, ad es. task.status_changed.
Stato Consegnato (verde), In attesa (ambra, in attesa o in nuovo tentativo), Non riuscito (rosso), Saltato.
Tentativi Quante volte SolaProjects ha già tentato.
Risposta Il codice di stato HTTP restituito dal vostro endpoint, errore se non è stata ricevuta alcuna risposta, oppure —.
(pulsante) Riprova su ogni consegna non consegnata.

Stato vuoto: Nessuna consegna — I tentativi di consegna compaiono qui quando si attiva un evento o invii un test.

#Scheda di prontezza del provider nativo

Stato della connessione e prerequisiti di configurazione delle integrazioni specifiche del provider. Una scheda per provider:

Fornitore Cosa fa
Slack Invia notifiche di progetto a Slack e ricevi comandi di attività da Slack.
Microsoft Teams Invia notifiche di progetto ai canali Teams e supporta le azioni Teams.
GitHub Collega eventi del repository, problemi, pull request e commit alle attività di progetto.
GitLab Collega merge request, problemi ed eventi di pipeline di GitLab alle attività di progetto.
Google Calendar Sincronizza le pietre miliari del progetto e le date delle attività con Google Calendar.
Google Drive Allega o sincronizza i documenti di progetto con le cartelle Google Drive.
OneDrive Allega o sincronizza i documenti di progetto con le cartelle OneDrive.
Zapier / IFTTT Esponi i trigger e le azioni di SolaProjects alle piattaforme no-code.

Ogni riquadro mostra uno stato (Disponibile, In attesa, Attivo, Non riuscito), la funzionalità e Rilevata una configurazione attiva del fornitore. oppure Il simulatore locale è disponibile; le credenziali di produzione sono impostazioni di attivazione. (il fornitore non è ancora attivo per l’organizzazione). Può anche mostrare Bloccato da configurazione mancante: …, Note di attivazione: …, Callback OAuth in attesa., Ultimo errore: …, l’ultimo messaggio o l’ultimo evento ricevuto.

#Eventi che potete inviare

Seleziona una o più voci nel modulo del webhook:

Evento Inviato quando
task.created Un'attività viene creata (anche da un webhook in arrivo).
task.updated Un'attività viene modificata.
task.status_changed Lo stato di un'attività cambia.
task.completed Un'attività viene contrassegnata come completata.
task.blocked Un'attività viene contrassegnata come bloccata.
comment.created Viene aggiunto un commento a un'attività.
doc.created Viene creato un documento di progetto.
time_entry.created Il tempo viene registrato.
milestone.completed Una milestone è completata.
sprint.started / sprint.completed Uno sprint inizia / si completa.
share_link.created Viene creato un link di condivisione per ospiti.
automation.run_failed / automation.rule_failed Un'esecuzione di automazione non riesce.
ai.suggestion_applied Un suggerimento dell'IA viene applicato.

Ogni richiesta è un JSON POST con le intestazioni X-SolaProjects-Event (tipo di evento), X-SolaProjects-Delivery (id di consegna) e X-SolaProjects-Signature (HMAC-SHA256 del corpo grezzo con il tuo segreto di firma), e User-Agent: SolaProjects-Webhooks/1.0. Verifica la firma prima di considerare attendibile una richiesta.

Nuovi tentativi. Una consegna non riuscita viene ritentata automaticamente dopo circa 1, 5, 15 e 60 minuti; dopo il quinto tentativo resta Non riuscita. Usa Riprova per ritentare manualmente.

#Attività

#Crea un webhook in uscita

  1. Aprite il progetto → Integrazioni → Nuovo webhook.

  2. Compila Nuovo webhook in uscita:

    Campo Obbligatorio Regole / predefiniti Note
    Nome Sì Fino a 160 caratteri. ad es. Pannello di controllo clienti.
    URL endpoint (HTTPS) Sì URL valido, fino a 2.048 caratteri, HTTPS pubblico. Segnaposto https://example.com/hooks/solaprojects. Gli indirizzi locali e di rete privata non sono accettati: "Usa un endpoint HTTPS pubblico. Gli URL di rete locale e privata sono bloccati."
    Eventi Sì Almeno uno. Vedi la tabella sopra.
    Attivo — Selezionato per impostazione predefinita. Deseleziona per salvarlo come Disabilitato.
  3. Clicchi Crea. Vede Webhook in uscita creato. e la finestra Segreto di firma: "Lo salvi ora — viene mostrato una sola volta e non può essere recuperato in seguito." Clicchi Copia (Copiato negli appunti.), conservi il segreto nel sistema ricevente, poi Fatto.

#Modifica, testa, ruota e archivia un webhook

Azione Passaggi Risultato
Modifica Cambia nome, URL, eventi oppure Attivo → Salva. Webhook in uscita aggiornato.
Prova Clicca su Test. Consegna di prova in coda. Una riga compare in Consegne recenti.
Ruota segreto Conferma Rigenera segreto — "Il segreto attuale smetterà di funzionare. Aggiorna i servizi collegati con il nuovo segreto." Segreto ruotato. e il nuovo segreto viene mostrato una sola volta.
Archivia Conferma Archivia webhook — "Questo webhook in uscita smetterà di inviare eventi del progetto." Webhook archiviato. Badge Archiviato; nessun'altra consegna; cronologia conservata.

#Crea un token webhook in entrata

  1. Clicca su Nuovo token in Token webhook in entrata.
  2. Nome (obbligatorio, fino a 160 caratteri) e Fornitore: Personalizzato (predefinito) oppure GitHub.
  3. Clicchi Crea → Token di webhook in entrata creato. Copi il Token webhook in entrata mostrato una sola volta: "Usi questo come token nell'URL del webhook in entrata. Mostrato una sola volta."

Il sistema esterno invia quindi POST /api/projects/webhooks/incoming/{token} con un corpo JSON (limite di 60 richieste al minuto per mittente):

Fornitore Corpo Cosa succede
Personalizzato {"title": "...", "description": "...", "priority": "high"} Crea un'attività privata in Da fare (priorità predefinita medium; titolo limitato a 180 caratteri). La risposta include il nuovo task_key.
Personalizzato {"task_key": "ALN-14", "comment": "..."} Aggiunge un commento interno a quell'attività.
GitHub Evento di emissione o di commento all'emissione Una segnalazione diventa un'attività; un commento su una segnalazione il cui titolo contiene una chiave attività (ad es. ALN-14) diventa un commento su quell'attività.

Qualsiasi altra richiesta viene rifiutata con "Webhook rifiutato."; un token revocato o errato riceve la stessa risposta. Attività e commenti sono attribuiti alla persona che ha creato il token.

Ruota emette un nuovo token e revoca immediatamente quello precedente (Token ruotato.). Revoca chiede conferma con Revoca token — «Le richieste che utilizzano questo token non avranno più accesso.» → Token revocato.

#Crea un token API pubblico

  1. Clicca su Nuovo token in API pubblica.

  2. Nome (obbligatorio, massimo 120 caratteri) e Capacità (almeno una; projects:read, tasks:read e time:read sono già selezionate):

    Capacità Consente
    projects:read Leggi questo progetto.
    tasks:read / tasks:write Leggi / crea e aggiorna le attività.
    time:read / time:write Leggi / crea le registrazioni di tempo.
  3. Crea → Token API creato. Copia il Token API del progetto: "Usalo come token Bearer per /api/v1. Mostrato una sola volta."

Le attività create tramite API attivano le stesse automazioni e gli stessi webhook delle attività create nell’app. Ruota → conferma Ruota token (“Il token attuale smetterà di funzionare. Aggiorna i servizi collegati con il nuovo token.”) → Token API ruotato. Revoca → Token API revocato.

#Riprova una consegna non riuscita

In Consegne recenti, fai clic su Riprova nella riga → Consegna ritentata. Controlla Stato e Risposta dopo un momento.

#Connetti un provider nativo

  1. Nella scheda del fornitore scegli il canale (ad esempio #projects per Slack) e fai clic su Connetti → Connessione a {Provider} avviata.
  2. Completa la finestra di autorizzazione Autorizzazione {Provider} con Completa callback (oppure Più tardi) → Integrazione nativa collegata.
  3. Una volta collegato, usa Invia test (Messaggio di test di {Provider} inviato.), Aggiorna ({Provider} aggiornato.) oppure Disconnetti ({Provider} disconnesso.).

I riquadri in modalità simulatore mostrano anche Simula evento ed Errore per verificare la configurazione prima che il fornitore vada online; non contattano il servizio reale.

#Stati

Oggetto Stati
Webhook in uscita Attivo, Disabilitato (salvato con Attivo deselezionato), Archiviato
Consegna In sospeso, Consegnato, Non riuscito, Saltato
Token in entrata / API Attivo, Inattivo, Revocato
Provider nativo Disponibile, In attesa, Attivo, Non riuscito

#Autorizzazioni

Ruolo Aprite la scheda Crea / modifica webhook, token, provider
Proprietario dell'organizzazione Sì Sì
Amministratore progetti Sì Sì
Responsabile progetti che è Responsabile di un progetto qui Sì Sì
Membro progetti, Osservatore del progetto, ospiti No No

Se la modifica delle integrazioni è disattivata per l'organizzazione, la scheda è in sola lettura (senza Nuovo, azioni di riga o Riprova). Una modifica rifiutata mostra «Le modifiche alle integrazioni sono disattivate o non consentite».; una pagina non aggiornata mostra «Ricarica e riprova». Segreti e token non vengono mai più mostrati dopo la finestra iniziale, nemmeno ai proprietari.

#Collegamento SolaCount dell'organizzazione

La voce Integrazioni nella barra laterale dello spazio di lavoro (/projects/settings/integrations) è una pagina diversa. Mostra se SolaProjects è collegato a SolaCount (Collegato, Pronto per la connessione, Integrazione sospesa, Disconnesso — cronologia conservata, …) e consente al proprietario dell’organizzazione o a un amministratore Finance di collegare, sospendere, disconnettere o verificare la connessione. Un singolo progetto può escludersi nella scheda Impostazioni (scheda Integrazioni → Progetto interno / finanze disabilitate). Vedi Budget e finanze e la panoramica di SolaProjects.

#Esempi pratici

#Esempio 1 — Le richieste diventano attività (quotidiano)

{User 1 name} vuole che le richieste dal sito web per {Showroom project name} (DEMO-FIT) diventino attività.

  1. Nuovo token → Nome Website enquiries, Provider Personalizzato → Crea; consegna il token allo sviluppatore web.
  2. Il sito web contabilizza {"title": "Quote request – reception desk", "priority": "high"}.
  3. L'attività ALN-31 Richiesta preventivo – reception compare in Da fare, privata, priorità Alta. La scheda del token mostra ultimo utilizzo 6 ott.

#Esempio 2 — Feed della dashboard cliente con un errore (scenario completo)

{User 2 name} collega la dashboard del sito di {Organization name}.

Passaggio Azione Risultato
1 Nuovo webhook: Dashboard del cantiere, https://hooks.company.example.com/projects, eventi task.status_changed, task.completed, milestone.completed. Webhook in uscita creato.; segreto di firma copiato nella dashboard.
2 Prova. Consegna di prova in coda.; riga Consegnato, Risposta 200.
3 {User 1 name} sposta ALN-12 su Completato. Due consegne: task.status_changed e task.completed, entrambe Consegnate.
4 La dashboard è non disponibile per manutenzione. La consegna successiva mostra In attesa, poi Non riuscita con Risposta 503; l'intestazione mostra Consegne non riuscite 1 in rosso; viene ritentata a circa 1, 5, 15, 60 minuti.
5 Ritorno alla dashboard; {User 2 name} clicca su Riprova. Consegna ritentata. → Consegnato.
6 L'IT sospetta che il segreto sia trapelato. {User 2 name} fa clic su Ruota segreto e conferma. Segreto ruotato.; nuovo segreto mostrato una sola volta; l'IT aggiorna la dashboard.

#Come si collega

Dove Link
Attività I token in ingresso e l'API creano attività e commenti; le modifiche delle attività inviano eventi.
Pianificazione Il completamento di una milestone e l'avvio/completamento di uno sprint inviano eventi.
Automazioni Agisci all'interno di SolaProjects; le esecuzioni non riuscite possono essere inviate come eventi.
Link di condivisione per gli ospiti Evento share_link.created.
AI Evento ai.suggestion_applied.
Monitoraggio del tempo Evento time_entry.created; capacità dell'API tempo.
Impostazioni Interruttore finanza SolaCount per progetto.

#Suggerimenti e problemi comuni

Problema Causa Soluzione
Scheda mancante. Piano inferiore a Premium o scaduto. Effettua l'upgrade o rinnova.
Usa un endpoint HTTPS pubblico… L'URL è http, localhost oppure un indirizzo privato. Usa un URL HTTPS pubblico.
Ho perso una chiave segreta o un token. Visualizzato una sola volta. Ruota e aggiorna l'altro sistema.
Le consegne non riuscite con un codice 4xx. Il tuo endpoint rifiuta la richiesta (spesso per un controllo della firma). Verifica che l'endpoint usi il segreto attuale.
Webhook rifiutato. sulle chiamate in entrata. Token revocato o errato, oppure il corpo non contiene title o task_key + comment. Controlla il token e il corpo.
Commento non aggiunto da GitHub. Il titolo dell'emissione non ha una chiave di attività. Inserisci la chiave (ad es. ALN-14) nel titolo della segnalazione.
L'API restituisce accesso negato. Il token non ha la capacità richiesta oppure è stato revocato. Crea un token con le autorizzazioni corrette.
Il provider indica Il simulatore locale è disponibile… Non ancora attivo per la tua organizzazione. Chiedete al supporto Solavel informazioni sull'attivazione.