Documentazione API

Entitlement API

Endpoint per verificare se un utente ha una licenza attiva per un plugin jtPlugin. Usato dai plugin al momento dell'avvio per decidere se abilitare le funzionalità Pro.

Panoramica

Il sistema di entitlement jtPlugin si basa su due sole informazioni: il plugin che chiede l'autorizzazione e l'identità dell'utente sulla piattaforma host. Non sono necessarie API key per i plugin Autodesk Fusion.

Il flusso è semplice: il plugin manda plugin_id + external_user_id, il backend verifica se esiste una licenza attiva collegata a quell'identità e risponde con authorized o denied.

Prerequisito per l'utente — Prima di usare il plugin, l'utente deve collegare il proprio account Autodesk su jtplugin.it → Dashboard → Account. Senza questo collegamento il backend risponde sempre identity_not_linked.

Endpoint

Produzione

POST https://jtplugin.it/api/entitlement/check
Content-Type: application/json

Nessun header Authorization richiesto per i plugin Autodesk Fusion. L'autenticazione avviene tramite il contenuto del body.

Request

Body (JSON)

{
  "plugin_id":      "jt-box-joint",
  "plugin_version": "1.0.0",
  "license_type":   "customer",
  "context": {
    "external_user_id": "FTT2MHYKECNN",
    "machine_id":       "a1b2c3d4e5f6...",
    "fusion_version":   "2.0.19800",
    "os":               "Windows"
  }
}

Campo	Obbligatorio	Descrizione
`plugin_id`	sì	Slug del plugin. Vedere la tabella degli slug registrati.
`plugin_version`	no	Versione del plugin. Usata per logging e analytics.
`license_type`	no	Sempre `customer` per Fusion. Default: `customer`.
`context.external_user_id`	sì	Autodesk User ID dell'utente corrente, letto da `app.userId`.
`context.machine_id`	no	Identificativo della macchina. Per logging.
`context.fusion_version`	no	Versione di Autodesk Fusion. Per logging.
`context.os`	no	Sistema operativo. Per logging.

Response — autorizzato

HTTP 200 OK

{
  "status":      "authorized",
  "reason":      null,
  "next_action": null,
  "license": {
    "plan":        "Individual",
    "valid_until": null
  },
  "capabilities": {
    "full_access": true
  },
  "meta": {
    "checked_at":  "2026-03-20T10:00:00Z",
    "cache_until": "2026-03-20T10:30:00Z"
  }
}

valid_until: null indica licenza perpetua. Il campo cache_until indica fino a quando il plugin può usare questa risposta senza ricontattare il server (tipicamente 30 minuti).

Il campo next_action può essere valorizzato anche su authorized— ad esempio quando la licenza è prossima alla scadenza. In quel caso il plugin mostra un banner non bloccante con next_action.label e link a next_action.url.

Response — negato

HTTP 200 OK — la chiamata ha avuto successo, la risposta è negativa ma non è un errore HTTP.

{
  "status": "denied",
  "reason": "identity_not_linked",
  "next_action": {
    "label": "Collega il tuo account Autodesk",
    "url":   "https://jtplugin.it/dashboard/account?action=link-autodesk"
  },
  "license":      null,
  "capabilities": {},
  "meta": {
    "checked_at":  "2026-03-20T10:00:00Z",
    "cache_until": "2026-03-20T10:05:00Z"
  }
}

Il plugin non costruisce messaggi propri: usa next_action.label come testo del bottone e apre next_action.url al click. Se il testo o gli URL cambiano in futuro, la risposta del backend si aggiorna automaticamente.

Reason codes

reason	Causa
`identity_not_linked`	L'Autodesk User ID non è collegato a nessun account jtPlugin.
`no_license`	L'account jtPlugin non ha nessuna licenza attiva per questo plugin.
`license_expired`	La licenza esiste ma è scaduta.
`license_revoked`	La licenza è stata revocata.

Errori HTTP

Codice	Causa	Comportamento suggerito
`400`	Body malformato o campi obbligatori mancanti.	Errore interno — loggare, non mostrare all'utente.
`404`	`plugin_id` non corrisponde a nessun plugin registrato.	Errore di configurazione — verificare lo slug.
`429`	Rate limit superato.	Backoff esponenziale: 1s, 2s, 4s. Poi usare cache locale.
`5xx`	Errore server jtPlugin.	Usare cache locale se disponibile, altrimenti modalità degradata.

Caching

Il campo meta.cache_until indica fino a quando il plugin può usare la risposta senza ricontattare il server. La risposta va persistita su disco in <plugin-root>/.jtplugin/entitlement-cache.json così da sopravvivere al riavvio dell'applicazione host.

Status	cache_until tipico
authorized	now + 30 minuti
denied	now + 5 minuti

Non cachare le risposte 404 e 5xx.

Comportamento offline

Se il server non è raggiungibile (timeout, assenza di rete, errore 5xx):

— Cache valida: usare la risposta cached e procedere normalmente.

— Cache scaduta o assente: modalità degradata. Mostrare un banner discreto e riprovare automaticamente dopo 10 minuti. Non bloccare il flusso di lavoro dell'utente per un problema temporaneo di connettività.

Slug plugin registrati

Il campo plugin_id deve corrispondere esattamente allo slug registrato. Lo slug non cambia nel tempo.

Plugin	Piattaforma	plugin_id
JT Box Joint	Autodesk Fusion	`jt-box-joint`
JT Flat Layout	Autodesk Fusion	`jt-flat-layout`