Perché collegarsi alla Trainfog API? 🔌

L’API Trainfog fornisce un’interfaccia programmatica potente per gestire il tuo catalogo prodotti, i workflow di generazione contenuti e gli asset e‑commerce. Collegarsi all’API consente di integrare senza attriti le funzionalità avanzate di AI e gestione dati di Trainfog nelle tue applicazioni, piattaforme e servizi di terze parti.
Questa integrazione è fondamentale per:

• Automazione dei contenuti: genera automaticamente descrizioni prodotto dettagliate, metadati SEO e copy di marketing con modelli AI avanzati, collegando l’output direttamente al catalogo prodotti.
• Sincronizzazione dei dati: mantieni prodotti, brand e categorie sincronizzati su più storefront, PIM (Product Information Management) o strumenti interni.
• Workflow personalizzati: crea applicazioni specializzate che sfruttano la logica backend di Trainfog, ad esempio attivando la generazione dei contenuti all’import di un nuovo prodotto o aggiornando i campi SEO in base all’analisi AI.

Autenticazione: flusso OAuth 2.0 Authorization Code Grant

L’accesso alla Trainfog API è protetto utilizzando il flusso OAuth 2.0 Authorization Code Grant. Questo protocollo standard è obbligatorio per un accesso sicuro e delegato, garantendo che le applicazioni client possano accedere ai dati utente senza gestire la password dell’utente.

Fase 1: configurazione applicazione e richiesta di autorizzazione

1. Registra la tua applicazione

Prima di iniziare il flusso, registra la tua applicazione per ottenere le credenziali necessarie:

1. Accedi alla dashboard del tuo account Trainfog.
2. Vai al pannello Developer.
3. Crea una nuova applicazione per ottenere il Client ID e il Client Secret.
4. Configura le Redirect URI ufficiali dove Trainfog invierà il codice di autorizzazione.

2. Richiedi il codice di autorizzazione (GET /oauth/authorize)

La tua applicazione avvia il flusso reindirizzando il browser dell’utente all’endpoint di autorizzazione Trainfog. All’utente viene richiesto di autenticarsi e concedere i permessi.

3. Gestisci il consenso dell’utente (POST /oauth/authorize)

Dopo che l’utente approva la tua applicazione nell’interfaccia Trainfog, il backend elabora il consenso e reindirizza l’utente alla tua redirect_uri.
Reindirizzamento riuscito:
YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=CSRF_STATE

Il AUTHORIZATION_CODE restituito è monouso e valido per un periodo molto breve.

Fase 2: scambio del token

In questa fase, il tuo backend sicuro scambia il codice temporaneo con token di accesso permanenti.

4. Scambia il codice per il token di accesso (POST /oauth/token)

La tua applicazione effettua una richiesta sicura, server‑to‑server, all’endpoint dei token.

Risposta di successo (contiene i token):

{
	"access_token": "ACCESS_TOKEN_VALUE",
	"refresh_token": "REFRESH_TOKEN_VALUE",
	"expires_in": 3600, // 1 ora
	"token_type": "Bearer",
	"workspace": "USER_WORKSPACE_ID",
	"scope": "elenco di scope concessi"
}

Fase 3: accesso all’API e refresh del token

5. Accesso alla Trainfog API

Devi usare l’access_token nell’header Authorization per tutte le richieste:
Authorization: Bearer YOUR_ACCESS_TOKEN

Note importanti:

• L’access_token è valido per 1 ora (3600 secondi).
• L’API Trainfog eredita automaticamente l’ID workspace e il contesto utente da questo token, eliminando la necessità di specificarlo in query o body.

6. Gestione scadenza token e refresh

Per garantire un servizio continuo, usa il refresh_token per ottenere una nuova coppia di token prima che l’attuale access_token scada o quando ricevi un errore 401 Unauthorized.
Richiedere un refresh (POST /oauth/token):

Risposta di successo: restituisce un nuovo access_token e un nuovo refresh_token (che dovresti salvare sostituendo il precedente), rinnovando la finestra di 1 ora.

Il tuo percorso di avvio rapido

Per informazioni dettagliate sugli endpoint disponibili, sui formati di richiesta/risposta e sugli esempi d’uso, consulta la documentazione completa del Riferimento API.

curl -X GET \
  https://api.trainfog.com/oauth/userinfo \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'