FONDAMENTI

Formato delle risposte

Le risposte dell'API adottano un involucro comune che separa l'esito dell'operazione dal contenuto restituito.

L'involucro comune

Campo	Tipo	Presenza
`success`	booleano	Sempre
`data`	oggetto dipendente dall'endpoint	Solo in caso di esito positivo
`error`	oggetto con `code` e `message`	Solo in caso di esito negativo
`errorMessage`	testo	Campo storico, presente solo su alcuni endpoint
`timestampUtc`	data e ora UTC	Sempre

Le proprietà nulle sono omesse dalla serializzazione: in una risposta positiva error non compare, in una negativa non compare data.

errorMessage è mantenuto per compatibilità con le integrazioni esistenti. Le nuove integrazioni leggono error.code per decidere il comportamento e error.message per la diagnostica.

{
  "success": true,
  "data": { },
  "timestampUtc": "2026-09-06T10:15:42.1183Z"
}

{
  "success": false,
  "error": {
    "code": "content_page_not_found",
    "message": "Content page not found."
  },
  "timestampUtc": "2026-09-06T10:15:42.1183Z"
}

Stato HTTP e campo success

Lo stato HTTP e il campo success non coincidono sempre: alcuni endpoint restituiscono 200 con success a false, per esempio la ricerca e lo stato dei pagamenti.

Il client verifica sempre success e usa lo stato HTTP solo per distinguere gli errori di trasporto.

Stato	Significato
`200`	Richiesta elaborata; l'esito applicativo è in `success`
`400`	Dati della richiesta non validi
`403`	Firma assente o non valida, oppure autorizzazione del sito mancante
`404`	La risorsa richiesta non esiste

Il 403 prodotto dal controllo della firma è testo semplice e non JSON.

Codici di errore

Codice	Endpoint	Significato
`website_id_invalid`	Risoluzione della pagina	L'header `WebsiteId` non è un GUID valido
`website_authorization_required`	Risoluzione della pagina	L'header `WebSecretId` è assente
`content_page_not_found`	Risoluzione della pagina	Nessuna route corrisponde all'URL richiesto
`payment_transaction_not_available`	Stato del pagamento	La transazione non esiste o non appartiene al sito

I codici sono stabili e pensati per essere confrontati dal codice. Il campo message è descrittivo e può cambiare.

Tipi e convenzioni di serializzazione

Le date sono in UTC, in formato ISO 8601.
Gli importi sono numeri decimali; la valuta è un campo separato.
Gli identificativi sono GUID in formato testuale.
Le enum dei contratti di contenuto sono serializzate come stringa, per esempio "Paragraph" o "HomePage".
Le enum dello stato dei pagamenti sono serializzate come numero: vanno mappate sui valori documentati e non sul nome.

Risposte fuori dall'involucro

Gli endpoint di privacy e consensi non adottano l'involucro: restituiscono direttamente l'oggetto richiesto, oppure uno stato 400, 404 o 200 senza corpo. Un client che li usa non deve cercare i campi success e data.