Connectors

Collega la tua app a servizi di terze parti come Slack, Resend ed ElevenLabs. Le credenziali sono cifrate e le azioni sono pre-autenticate.

I Connectors ti permettono di integrare servizi esterni nella tua app senza dover gestire chiavi API grezze nel codice. Configuri una connessione una volta sola, la associ al tuo progetto e chiami azioni predefinite dalla tua app. Le credenziali sono cifrate a riposo e non vengono mai esposte al tuo codice frontend.

Connectors disponibili

Connector	Categoria	Tipo di auth	Cosa fa
Resend	Comunicazioni	API key	Invia email transazionali, invia email in batch, elenca i domini verificati
Slack	Comunicazioni	OAuth	Pubblica messaggi, elenca canali e utenti, reagisce ai messaggi, legge i thread
ElevenLabs	AI	API key	Text-to-speech, elenca le voci disponibili, genera effetti sonori

Nuovi connectors vengono aggiunti regolarmente.

Come funzionano i Connectors

1. Crei una connessione — fornisci le credenziali (una API key o accedi tramite OAuth)
2. Associ la connessione a un progetto — questo autorizza il progetto a utilizzare quelle credenziali
3. La tua app chiama le azioni — la richiesta passa attraverso Proyecta Cloud, che inietta le credenziali lato server

Il codice della tua app non tocca mai la API key grezza né il token OAuth. Il sistema dei Connectors gestisce l’autenticazione, il rate limiting e l’audit logging.

Configura un Connector

1. Apri il tuo progetto nel builder
2. Vai su Settings > Connectors
3. Clicca su un connector dal catalogo (ad es., Resend)
4. Inserisci le tue credenziali:
   • Connectors con API key (Resend, ElevenLabs): Incolla la tua chiave segreta
   • Connectors OAuth (Slack): Accedi e autorizza l’accesso
5. Assegna un nome alla connessione (ad es., “Production Resend”)
6. La connessione viene testata automaticamente e contrassegnata come Active se valida

Leggi da un Connector nella tua app

La tua app può leggere un’API di terze parti direttamente dal browser senza che la chiave API finisca mai nel bundle. La credenziale resta cifrata sulla piattaforma; la tua app indica solo il connector, l’azione e un input tipizzato, e la piattaforma effettua la chiamata al posto tuo.

import { useConnectorData, useHttpRead } from '@/hooks/useConnector.ts';

// A connector's own read action, as a cached query
const { data, isLoading, error } = useConnectorData('eleven-labs', 'listVoices');

// The generic HTTP-read connector, by endpoint name
const { data: feed } = useHttpRead('news-feed', { limit: 10 });

Ci sono due protezioni da conoscere, perché sono volute:

• Solo letture. Sono raggiungibili unicamente le azioni che la piattaforma ha contrassegnato come sicure per il browser — tutto il resto restituisce 403. Le scritture (pubblicare su Slack, inviare email, addebitare una carta) non sono mai raggiungibili dal browser.
• Non puoi passare un URL o un host. Per il connector generico http-read l’input è { endpointKey, params }, e l’URL dietro endpointKey viene configurato da te, il proprietario dell’app — non dal codice dell’app. Le risposte sono memorizzate in cache lato server e soggette a rate limiting, poiché le chiavi di terze parti hanno quote.

Un 404 significa che il proprietario non ha ancora collegato quel connector — è il caso che vale la pena gestire nella tua UI.

Lascia che l’AI si occupi dell’integrazione

Non devi scrivere il codice per i Connectors a mano. Il builder AI conosce quali Connectors sono associati al tuo progetto e può generare l’integrazione per te:

• "Invia un'email di benvenuto quando gli utenti si registrano" — usa il Connector Resend
• "Pubblica un messaggio su Slack quando arriva un nuovo ordine" — usa il Connector Slack
• "Riproduci una narrazione audio sulla pagina dell'articolo" — usa il Connector ElevenLabs

Riferimento alle azioni dei Connectors

Resend (connectorId: 'resend')

Azione	Effetti collaterali	Descrizione
sendEmail	write	Invia una singola email transazionale
sendBatch	write	Invia più email contemporaneamente
listDomains	read	Elenca i domini di invio verificati

Slack (connectorId: 'slack')

Azione	Effetti collaterali	Descrizione
postMessage	write	Pubblica un messaggio in un canale
listChannels	read	Elenca i canali del workspace
listUsers	read	Elenca i membri del workspace
reactToMessage	write	Aggiunge una reaction con emoji
getThread	read	Recupera le risposte in un thread

ElevenLabs (connectorId: 'eleven-labs')

Azione	Effetti collaterali	Descrizione
textToSpeech	write	Converte testo in audio vocale
listVoices	read	Elenca le voci disponibili
generateSoundEffect	write	Genera un effetto sonoro con l’AI

Stati della connessione

Stato	Significato
Active	Le credenziali sono valide e la connessione è pronta all’uso
Broken	Le credenziali sono scadute o sono state revocate — aggiornale per ripristinarla

Sicurezza

• Le credenziali sono cifrate con AES-256-GCM a riposo
• Le azioni sono soggette a rate limiting di 1.000 richieste al minuto per connector per progetto
• Ogni chiamata a un’azione viene registrata con un audit trail (connessione, azione, durata, stato)
• Le connessioni sono limitate all’intero workspace

FAQ

Posso usare la stessa connessione su più progetti?

Sì. Crea la connessione una volta sola e associala a qualsiasi numero di progetti nello stesso workspace.

Cosa succede se la mia API key scade o viene revocata?

Lo stato della connessione cambia in Broken. Aggiorna le credenziali in Settings > Connectors per ripristinarla.

Posso chiamare le azioni dei Connectors dal frontend?

La tua app non le detiene mai. Le azioni di lettura sicure per il browser vengono inoltrate tramite proxy attraverso Proyecta Cloud, che inietta le credenziali lato server, quindi la chiave non finisce mai nel tuo bundle. Le azioni di scrittura non sono affatto raggiungibili dal browser.

Posso aggiungere Connectors personalizzati?

Non ancora. Le definizioni di Connectors personalizzati sono nella roadmap.

Prossimamente

• Connectors aggiuntivi (Google, Twilio, SendGrid e altri)
• Definizioni di Connectors personalizzati — integra la tua API
• Ricezione di webhook per eventi in entrata dai servizi connessi
• OAuth gateway — mantieni i token lato server anche per i flussi avviati dal client