Guida Tecnica: Migrazione da OAuth 1 a OAuth V2

Azione richiesta: È necessario aggiornare tutti i puntatori endpoint nel codice sorgente . Si raccomanda l'uso di variabili d'ambiente o una procedura di "find and replace" globale per riflettere il cambio del TLD da .it a .com .

3. Evoluzione della Gestione Token

3.1 Mappatura degli Endpoint

La V2 adotta una nomenclatura RESTful pluralizzata per la gestione delle risorse token . L'endpoint per le operazioni sui token passa infatti da /token a /tokens .

3.2 Creazione e Parametri (TokenCreate)

Nella V2, l'endpoint POST /tokens estende il controllo granulare oltre i semplici campi scopes e ttl . Sono ora supportati i seguenti parametri definiti nello schema TokenCreate: name (identificatore mnemonico per l'audit log), limit_total (tetto massimo di richieste), limit_paid (limite massimo di richieste a pagamento), ips (whitelist di indirizzi IP autorizzati), e wallet_limit (budget specifico allocato dal Wallet globale) .

3.3 Aggiornamento e Refresh-Token Flow

Mentre in V1 il metodo PATCH era limitato alla modifica parziale dei metadati, in V2 il metodo PATCH /tokens/{token} è standardizzato per supportare il flusso di rotazione (refresh-token) . Questo consente di ruotare le credenziali e aggiornare i permessi senza invalidare l'identificatore esistente, garantendo continuità operativa e sicurezza .

3.4 Confronto Struttura JSON

La V2 restituisce l'oggetto TokenDetail (parte dello schema TokenListOrDetail), integrando limiti e metadati precedentemente non disponibili.

Risposta OAuth 1 (Legacy):

{
  "scopes": ["POST:valutometro.altravia.com/valutazione"],
  "expire": 1634223407,
  "token": "5f8711afe4754a532a7a8358",
  "success": true,
  "message": "",
  "error": null
}

Risposta OAuth V2 (TokenDetail) :

{
  "name": "Production_Token_01",
  "token": "6f9822bgf5862b643b8b9469",
  "expire": 1735689600,
  "scopes": [
    {
      "domain": "imprese.openapi.it",
      "endpoint": "base",
      "method": "GET"
    }
  ],
  "limits": {
    "limit_total": 1000,
    "limit_paid": 500,
    "wallet_limit": 50.00
  },
  "ips": ["192.168.1.1"],
  "success": true
}

4. Dal Credito (V1) al Wallet (V2)

V2 introduce la gestione economica tramite il modulo Wallet, che garantisce trasparenza transazionale . L'ispezione del saldo avviene ora tramite GET /wallet che sostituisce il vecchio /credit . La tracciabilità transazionale è assicurata da GET /wallet/transactions che permette l'accesso alla cronologia dei movimenti . A differenza del valore statico della V1, la cronologia in V2 è paginata, consentendo analisi dettagliate per account ad alto volume transazionale .

5. Sistemi di Monitoraggio: Dai Contatori alle Statistiche Avanzate

Il sistema /counters della V1, basato su aggregazioni temporali rigide, è sostituito dal motore /stats multidimensionale . La granularità della V2 permette aggregazioni per Token, IP, Dominio e Scope . Le chiamate come GET /stats/ips identificano gli indirizzi IP unici, GET /stats/apis aggrega i consumi per dominio API, e GET /stats/apis/{domain} fornisce la ripartizione esatta degli scope utilizzati all'interno di un dominio specifico . Sono inoltre disponibili registri integrati per la visibilità degli errori tramite /errors .

6. Nuove Funzionalità Esclusive di OAuth V2

La versione 2.0.0 introduce endpoint di monitoraggio precedentemente assenti :

• Callbacks (/callbacks): Endpoint per il monitoraggio e la verifica dello stato di consegna dei callback generati dalle API .
• Subscriptions (/subscriptions): Gestione e ispezione degli abbonamenti attivi associati all'account .
• Error Logs (/errors): Accesso programmatico ai log di errore (ErrorLog), essenziale per il debugging in tempo reale delle integrazioni .

7. Tabella Rapida di Riferimento per Sviluppatori