Automatizza Transept con le API

Crea una chiave API personale in Impostazioni → Sviluppatore. È disponibile in ogni piano, incluso quello Gratuito — non ci sono barriere all'accesso, l'unico limite all'utilizzo è il Suo saldo parole. Assegni un nome alla chiave, imposti facoltativamente una scadenza e copi il segreto quando viene mostrato: appare una sola volta e non può essere recuperato in seguito. Può revocare una chiave in qualsiasi momento dalla stessa pagina.

Le richieste vengono autenticate tramite la chiave nell'header Authorization: Bearer tsk_live_… — solo nell'header, mai nell'URL.

Crea un documento a partire da testo semplice, HTML o Markdown, oppure carica un file — gli stessi formati accettati dall'app. Puoi anche importare una tabella di stringhe (.tstrings.json): un formato strutturato per testi UI o stringhe di gioco, in cui ogni stringa è un'unità con una chiave stabile e il proprio contesto — una nota su cosa sia, dove appaia, un limite di caratteri e il significato dei relativi segnaposto. Tutte queste informazioni arrivano al modello; i segnaposto come {name} sono protetti da rimozioni o rinomine, e i plurali vengono espansi in base alla lingua (una forma inglese ne diventa due in tedesco, quattro in ucraino). Eventuali traduzioni già presenti nel file vengono importate così come sono, gratuitamente, e alimentano immediatamente la memoria di traduzione.

Un'esecuzione di gruppo traduce in più lingue contemporaneamente. Indica il documento, il Workflow o il template da eseguire e le lingue di destinazione; Transept crea le versioni linguistiche mancanti ed esegue il Workflow su ciascuna. Un unico ID tiene traccia dell'intero processo: interrogalo per monitorare l'avanzamento di ogni lingua e sapere se è in attesa di revisione.

Per le esecuzioni ricorrenti, invia di nuovo il file attuale di una tabella di stringhe e Transept individuerà le modifiche: le stringhe invariate manterranno le proprie traduzioni (e le revisioni già effettuate) e l'esecuzione interesserà solo le unità nuove o realmente modificate — la versione API di Esegui solo per ciò che è cambiato. Una chiamata di creazione job accetta anche un header Idempotency-Key, così un nuovo tentativo dopo un problema temporaneo di rete restituirà il risultato originale invece di un secondo documento e un secondo addebito.

Invece di procedere con il polling, registra un URL e Transept invierà una notifica push al termine o al fallimento di un'esecuzione, quando una revisione è pronta per essere esaminata, al completamento di un caricamento o quando un'esportazione è disponibile. Ogni notifica include un header HMAC-SHA256 X-Transept-Signature: t=…,v1=… affinché il destinatario possa verificarne l'origine; se l'endpoint fallisce, l'invio viene riprovato con una strategia di backoff prima della disattivazione.

Un Workflow può anche attivarsi automaticamente tramite un'automazione del database di Notion: indirizzi il webhook dell'automazione all'URL del trigger e Transept eseguirà il Workflow sulla pagina modificata. Il problema è che un webhook di Notion non trasmette mai il contenuto della pagina — indica solo quale pagina ha attivato il trigger. Transept legge la pagina tramite la Sua connessione Notion, quindi devono essere soddisfatte entrambe le condizioni, altrimenti ogni attivazione verrà rifiutata con un errore di accesso e la scheda del trigger mostrerà la nota «impossibile leggere la pagina Notion»:

• Colleghi Notion in Transept — in Impostazioni → Integrazioni. Si tratta del link OAuth una tantum che consente a Transept di leggere per Suo conto.
• Condivida il database di origine con l'integrazione all'interno di Notion — apra il database (o la pagina), faccia clic sul menu •••, scelga Connessioni e aggiunga Transept. Collegare Notion nelle Impostazioni non garantisce di per sé l'accesso a un database specifico; senza questo passaggio la connessione è attiva, ma la pagina rimane illeggibile.
• Attivazione tramite modifica di una proprietà, non solo del corpo del testo. Le automazioni di Notion si attivano in base alle modifiche delle proprietà (e all'aggiunta di pagine), quindi la sola modifica del corpo di una pagina potrebbe non far scattare nulla. Il metodo più affidabile consiste nell'utilizzare una proprietà Stato monitorata dall'automazione: ne cambi il valore (ad esempio in «Pronto per la traduzione») e sarà proprio tale modifica ad attivare il trigger.

L'elenco completo degli endpoint è pubblicato come specifica OpenAPI, importabile in n8n, Zapier o in un generatore di codice: consultala su /public/v1/docs della tua API Transept o scarica il JSON non elaborato da /public/v1/openapi.json. Le esecuzioni avviate tramite API vengono conteggiate nel saldo parole esattamente come nell'editor dell'app.