{ "components": { "schemas": { "AccountClosure": { "additionalProperties": false, "properties": { "case_id": { "format": "uuid", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "confirmed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "scope": { "enum": [ "account", "workspace" ], "type": "string" }, "status": { "type": "string" } }, "required": [], "type": "object" }, "AccountClosureInput": { "additionalProperties": false, "properties": { "confirm": { "const": true, "type": "boolean" }, "current_password": { "type": "string" }, "request_id": { "type": "string" }, "scope": { "enum": [ "account", "workspace" ], "type": "string" } }, "required": [ "scope", "current_password", "confirm", "request_id" ], "type": "object" }, "AccountClosureList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/AccountClosure" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "AccountClosureReview": { "additionalProperties": false, "properties": { "acknowledge_finance": { "type": "boolean" }, "approve": { "type": "boolean" }, "decision": { "type": "string" } }, "required": [ "approve", "decision" ], "type": "object" }, "AccountCorrection": { "additionalProperties": false, "properties": { "current_password": { "type": "string" }, "email": { "format": "email", "type": "string" }, "name": { "maxLength": 120, "type": "string" } }, "required": [ "name", "current_password" ], "type": "object" }, "Activation": { "additionalProperties": false, "example": { "created_at": "2026-10-18T00:00:00Z", "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "generation": 1, "id": "44444444-4444-4444-8444-444444444444", "last_seen_at": "2026-10-18T00:00:00Z", "license_id": "33333333-3333-4333-8333-333333333333", "product_id": "11111111-1111-4111-8111-111111111111", "released_at": null, "status": "active", "virtual_machine": false }, "properties": { "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "device_id": { "description": "Impronta del dispositivo specifica del prodotto, normalmente di 64 caratteri esadecimali minuscoli, derivata dall'SDK.", "type": "string" }, "device_name": { "description": "Etichetta del dispositivo leggibile dall'utente, non un'identità di sicurezza.", "type": "string" }, "generation": { "description": "Generazione dell'attivazione usata per invalidare le vecchie credenziali dei dispositivi.", "type": "integer" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "last_seen_at": { "description": "Timestamp dell'ultima attività del dispositivo osservata dal server, UTC.", "format": "date-time", "type": "string" }, "lease_expires_at": { "anyOf": [ { "description": "Scadenza del lease di un posto flottante; i posti scaduti possono essere recuperati.", "format": "date-time", "type": "string" }, { "description": "Scadenza del lease di un posto flottante; i posti scaduti possono essere recuperati.", "type": "null" } ], "description": "Scadenza del lease di un posto flottante; i posti scaduti possono essere recuperati." }, "license_id": { "description": "UUID della licenza, distinto dal segreto lv_lic_.", "format": "uuid", "type": "string" }, "product_id": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" }, "released_at": { "anyOf": [ { "description": "Timestamp del rilascio; null fino al rilascio.", "format": "date-time", "type": "string" }, { "description": "Timestamp del rilascio; null fino al rilascio.", "type": "null" } ], "description": "Timestamp del rilascio; null fino al rilascio." }, "session_id": { "description": "Identificativo della sessione di un'istanza flottante; può essere omesso per le licenze vincolate al dispositivo.", "type": "string" }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "active", "released" ], "type": "string" }, "virtual_machine": { "description": "Indica se l'SDK ha rilevato una macchina virtuale.", "type": "boolean" } }, "required": [ "id", "product_id", "license_id", "device_id", "virtual_machine", "device_name", "status", "generation", "created_at", "last_seen_at", "released_at" ], "type": "object" }, "ActivationList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/Activation" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "AdminPlanList": { "additionalProperties": false, "properties": { "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "items": { "items": { "$ref": "#/components/schemas/Price" }, "type": "array" }, "settings": { "$ref": "#/components/schemas/DefaultPlan" } }, "required": [], "type": "object" }, "AttemptList": { "additionalProperties": false, "properties": { "items": { "anyOf": [ { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/WebhookAttempt" }, "type": "array" }, { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "type": "null" } ], "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo." } }, "required": [], "type": "object" }, "Audit": { "additionalProperties": false, "properties": { "action": { "description": "Identificativo dell'azione di controllo, ad esempio product.create o license.renew.", "type": "string" }, "actor_id": { "description": "UUID dell'account responsabile dell'azione.", "format": "uuid", "type": "string" }, "actor_kind": { "description": "Origine dell'azione: session, api_key o system.", "enum": [ "session", "api_key", "system" ], "type": "string" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "type": "string" }, "resource_id": { "description": "UUID della risorsa interessata.", "maxLength": 36, "type": "string" } }, "required": [ "id", "action", "resource_id", "created_at" ], "type": "object" }, "AuditList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/Audit" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" } }, "required": [ "items", "limit", "offset" ], "type": "object" }, "AutoRenewal": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Importo in centesimi; le registrazioni contabili possono essere accrediti positivi o addebiti negativi.", "minimum": 0, "type": "integer" }, "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "type": "string" }, "enabled": { "description": "Indica se l'endpoint webhook è abilitato.", "type": "boolean" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "type": "string" }, "plan_name": { "description": "Nome visualizzato del piano.", "type": "string" }, "policy_version": { "description": "Revisione della politica di servizio accettata al salvataggio del rinnovo automatico.", "type": "string" }, "price_version": { "description": "Revisione del prezzo congelata; un input obsoleto può causare PLAN_VERSION_CONFLICT.", "type": "string" }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "disabled", "enabled", "insufficient_balance", "price_changed", "plan_changed", "plan_unavailable", "account_unavailable" ], "type": "string" }, "term_months": { "description": "Numero di mesi della durata acquistata.", "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "updated_at": { "description": "Timestamp dell'ultimo aggiornamento in UTC.", "format": "date-time", "type": "string" }, "version": { "description": "Revisione della configurazione del rinnovo automatico.", "type": "string" } }, "required": [ "mode", "enabled", "plan", "plan_name", "currency", "price_version", "term_months", "amount_cents", "status", "version", "updated_at" ], "type": "object" }, "AutoRenewalInput": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "enabled": { "type": "boolean" }, "expected_version": { "type": "string" }, "overage_accepted": { "description": "Autorizzazione esplicita separata degli sforamenti a pagamento visualizzati.", "type": "boolean" }, "plan": { "type": "string" }, "policy_version": { "description": "Versione immutabile della politica attualmente pubblicata. Obbligatoria per le azioni protette dal consenso dopo che l'operatore ha pubblicato una politica, in entrambi gli ambienti di pagamento.", "type": "string" }, "price_version": { "type": "string" }, "term_months": { "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "terms_accepted": { "description": "Accettazione esplicita, non preselezionata per impostazione predefinita.", "type": "boolean" } }, "required": [ "enabled", "expected_version" ], "type": "object" }, "AutoRenewalResult": { "additionalProperties": false, "properties": { "next_renewal_at": { "anyOf": [ { "description": "Timestamp previsto del prossimo rinnovo in UTC; può essere null se disabilitato o non necessario.", "format": "date-time", "type": "string" }, { "description": "Timestamp previsto del prossimo rinnovo in UTC; può essere null se disabilitato o non necessario.", "type": "null" } ], "description": "Timestamp previsto del prossimo rinnovo in UTC; può essere null se disabilitato o non necessario." }, "setting": { "$ref": "#/components/schemas/AutoRenewal", "description": "Configurazione corrente del rinnovo automatico." } }, "required": [ "setting", "next_renewal_at" ], "type": "object" }, "BatchInput": { "additionalProperties": false, "properties": { "days": { "description": "Obbligatorio per renew: giorni di validità aggiuntivi, 1–36500; non usato dalle altre operazioni.", "maximum": 36500, "minimum": 1, "type": "integer" }, "duration_days": { "description": "Durata comune per le voci create che omettono duration_days. Ogni voce può sostituirla. Obbligatoria per le voci timed/trial senza una propria durata; omettere per la creazione perpetual.", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "entries": { "description": "Obbligatorio per create: 1–100 voci cliente; omettere per le altre operazioni.", "items": { "additionalProperties": false, "properties": { "customer": { "description": "Etichetta del cliente definita dal fornitore, distinta dall'email del portale clienti.", "maxLength": 120, "type": "string" }, "customer_email": { "description": "Email associata del portale clienti; vuota quando non assegnata.", "maxLength": 254, "type": "string" }, "duration_days": { "description": "Durata di creazione specifica della licenza; sostituisce BatchInput.duration_days. Omettere per usare la durata di creazione comune.", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] } }, "required": [], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" }, "ids": { "description": "Obbligatorio per renew, revoke e apply_policy: 1–100 UUID distinti di licenze; omettere per create.", "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "operation": { "description": "Nome dell'operazione; i batch supportano create/renew/revoke/apply_policy e le richieste offline activate/deactivate.", "enum": [ "create", "renew", "revoke", "apply_policy" ], "type": "string" }, "policy_id": { "description": "Obbligatorio per create e apply_policy: UUID della politica di licenza di destinazione.", "format": "uuid", "type": "string" }, "preview_token": { "description": "Token cifrato di conferma dell'anteprima obbligatorio per apply_policy; valido per 600 secondi e invalidato dalle modifiche alle risorse.", "type": "string", "writeOnly": true }, "product_id": { "description": "Obbligatorio per create: UUID del prodotto per le nuove licenze.", "format": "uuid", "type": "string" }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "request_id", "operation" ], "type": "object" }, "BatchItem": { "additionalProperties": false, "example": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }, "properties": { "customer": { "description": "Etichetta del cliente definita dal fornitore, distinta dall'email del portale clienti.", "type": "string" }, "customer_email": { "description": "Email associata del portale clienti; vuota quando non assegnata.", "type": "string" }, "duration_days": { "description": "Giorni specifici della licenza dalla prima attivazione. Obbligatori 1–36500 per l'emissione timed/trial; assenti/null per perpetual. Non vengono mai memorizzati nella politica.", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "type": "null" } ], "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale." }, "first_activated_at": { "anyOf": [ { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, { "description": "Timestamp della prima attivazione riuscita; null prima dell'attivazione e invariato da rinnovi o trasferimenti.", "type": "null" } ], "description": "Timestamp della prima attivazione riuscita; null prima dell'attivazione e invariato da rinnovi o trasferimenti." }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "license_key": { "description": "Chiave di licenza completa del cliente fornita all'attivazione. Il codice di inizializzazione del prodotto e gli esempi scaricabili non contengono questo segreto. Le richieste offline usano la credenziale fornita dall'SDK.", "type": "string" }, "operation": { "description": "Nome dell'operazione; i batch supportano create/renew/revoke/apply_policy e le richieste offline activate/deactivate.", "enum": [ "create", "renew", "revoke", "apply_policy" ], "type": "string" } }, "required": [ "id" ], "type": "object" }, "BatchResult": { "additionalProperties": false, "properties": { "count": { "description": "Conteggio nel gruppo corrente oppure numero di record elaborati da un batch.", "type": "integer" }, "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/BatchItem" }, "type": "array" }, "operation": { "description": "Nome dell'operazione; i batch supportano create/renew/revoke/apply_policy e le richieste offline activate/deactivate.", "enum": [ "create", "renew", "revoke", "apply_policy" ], "type": "string" }, "request_id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } }, "required": [ "request_id", "operation", "items", "count" ], "type": "object" }, "BillingEmailPreview": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "link": { "format": "uri", "type": "string" }, "reply_to": { "description": "Email pubblica dell'assistenza e Reply-To per le email di fatturazione. Un valore vuoto nasconde il contatto. Non modifica l'indirizzo SMTP From esistente né crea una casella di posta.", "maxLength": 254, "type": "string" }, "subject": { "type": "string" }, "to": { "format": "email", "type": "string" } }, "required": [ "id", "to", "subject", "body", "link" ], "type": "object" }, "BillingEmailTestInput": { "additionalProperties": false, "properties": { "kind": { "enum": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem" ], "type": "string" }, "locale": { "default": "zh", "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "to": { "format": "email", "type": "string" } }, "required": [ "kind", "to" ], "type": "object" }, "BillingJob": { "additionalProperties": false, "properties": { "attempts": { "description": "Numero cumulativo di tentativi dell'attività.", "type": "integer" }, "available_at": { "description": "Primo orario UTC in cui l'attività può essere eseguita.", "format": "date-time", "type": "string" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "last_error": { "description": "Categoria dell'errore più recente; può essere vuota.", "type": "string" }, "month": { "description": "Mese UTC YYYY-MM; i valori di query omessi usano il mese corrente. Le attività di fatturazione richiedono un mese concluso.", "type": "string" }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "pending", "running", "done", "failed" ], "type": "string" } }, "required": [ "id", "month", "status" ], "type": "object" }, "BillingJobList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/BillingJob" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "BillingNotificationPreference": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expiry_reminder": { "default": true, "type": "boolean" }, "locale": { "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "purchase_success": { "default": true, "type": "boolean" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem", "locale", "version", "updated_at" ], "type": "object" }, "BillingNotificationPreferenceInput": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expected_version": { "description": "Versione dalla richiesta GET; vuota per una preferenza non ancora salvata. Un valore obsoleto restituisce BILLING_EMAIL_PREFERENCE_CONFLICT.", "type": "string" }, "expiry_reminder": { "default": true, "type": "boolean" }, "locale": { "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "purchase_success": { "default": true, "type": "boolean" } }, "required": [ "expected_version" ], "type": "object" }, "BillingNotificationPreferencesResult": { "additionalProperties": false, "properties": { "platform": { "$ref": "#/components/schemas/BillingNotificationSettings" }, "preferences": { "$ref": "#/components/schemas/BillingNotificationPreference" }, "recipient": { "format": "email", "type": "string" } }, "required": [ "preferences", "platform", "recipient" ], "type": "object" }, "BillingNotificationSettings": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expiry_reminder": { "default": true, "type": "boolean" }, "purchase_success": { "default": true, "type": "boolean" }, "reminder_days": { "default": [ 7 ], "description": "Soglie prima della fine della copertura continua, espresse in giorni di 24 ore. Memorizzate in ordine crescente. Un worker avviato in ritardo seleziona soltanto la soglia rimanente più vicina, non tutti i promemoria mancati.", "items": { "maximum": 90, "minimum": 1, "type": "integer" }, "maxItems": 10, "minItems": 1, "type": "array", "uniqueItems": true }, "support_email": { "description": "Email pubblica dell'assistenza e Reply-To per le email di fatturazione. Un valore vuoto nasconde il contatto. Non modifica l'indirizzo SMTP From esistente né crea una casella di posta.", "maxLength": 254, "type": "string" }, "version": { "type": "string" } }, "required": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem", "reminder_days", "support_email", "version" ], "type": "object" }, "BillingNotificationSettingsInput": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expected_version": { "description": "Versione dalla richiesta GET. Un valore obsoleto restituisce BILLING_EMAIL_SETTINGS_CONFLICT.", "type": "string" }, "expiry_reminder": { "default": true, "type": "boolean" }, "purchase_success": { "default": true, "type": "boolean" }, "reminder_days": { "default": [ 7 ], "description": "Soglie prima della fine della copertura continua, espresse in giorni di 24 ore. Memorizzate in ordine crescente. Un worker avviato in ritardo seleziona soltanto la soglia rimanente più vicina, non tutti i promemoria mancati.", "items": { "maximum": 90, "minimum": 1, "type": "integer" }, "maxItems": 10, "minItems": 1, "type": "array", "uniqueItems": true }, "support_email": { "description": "Email pubblica dell'assistenza e Reply-To per le email di fatturazione. Un valore vuoto nasconde il contatto. Non modifica l'indirizzo SMTP From esistente né crea una casella di posta.", "maxLength": 254, "type": "string" } }, "required": [ "expected_version" ], "type": "object" }, "BundleInput": { "additionalProperties": false, "properties": { "language": { "description": "Identificativo del linguaggio SDK per il bundle scaricabile.", "enum": [ "go", "java", "c", "cpp", "csharp", "python", "javascript", "rust", "ruby" ], "type": "string" } }, "required": [ "language" ], "type": "object" }, "BuyPlan": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "overage_accepted": { "description": "Autorizzazione esplicita separata degli sforamenti a pagamento visualizzati.", "type": "boolean" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "policy_version": { "description": "Versione immutabile della politica attualmente pubblicata. Obbligatoria per le azioni protette dal consenso dopo che l'operatore ha pubblicato una politica, in entrambi gli ambienti di pagamento.", "type": "string" }, "price_version": { "type": "string" }, "renewal": { "default": false, "description": "Rinnovo anticipato esplicito. Il pagamento viene incassato subito e la copertura prepagata viene estesa immediatamente. Il ciclo della quota successivo segue la copertura pagata o regalata esistente. Nessun azzeramento dell'utilizzo corrente. Rinnovare l'ultimo piano pagato e la relativa valuta; anche i clienti con pacchetti scaduti possono acquistare normalmente.", "type": "boolean" }, "request_id": { "maxLength": 80, "type": "string" }, "term_months": { "default": 1, "description": "Durata del contratto. L'omissione usa un mese come valore predefinito. La modifica della durata riutilizzando request_id restituisce 409.", "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "terms_accepted": { "description": "Accettazione esplicita, non preselezionata per impostazione predefinita.", "type": "boolean" } }, "required": [ "plan", "currency", "price_version", "request_id" ], "type": "object" }, "CSRF": { "additionalProperties": false, "properties": { "csrf_token": { "type": "string" } }, "required": [ "csrf_token" ], "type": "object" }, "CancelCustomerRefund": { "additionalProperties": false, "properties": { "confirm_service_stays_cancelled": { "description": "Obbligatorio quando l'annullamento del servizio è già stato eseguito prima della revisione. Una domanda esplicita con ambito definito in sospeso può essere ritirata senza interrompere o ripristinare il servizio.", "type": "boolean" } }, "type": "object" }, "ChangePassword": { "additionalProperties": false, "properties": { "current_password": { "description": "12–128 byte UTF-8, non caratteri", "type": "string", "writeOnly": true }, "password": { "description": "12–128 byte UTF-8, non caratteri", "type": "string", "writeOnly": true }, "password_confirmation": { "description": "Obbligatorio e deve corrispondere esattamente a password", "type": "string", "writeOnly": true } }, "required": [ "current_password", "password", "password_confirmation" ], "type": "object" }, "ClosureExportCredential": { "additionalProperties": false, "properties": { "download_url": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "export_deadline": { "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "ClosureExportLogin": { "additionalProperties": false, "properties": { "current_password": { "type": "string" }, "email": { "format": "email", "type": "string" } }, "required": [ "email", "current_password" ], "type": "object" }, "CommerceNotice": { "additionalProperties": false, "properties": { "body": { "description": "Corpo dell'avviso di servizio.", "type": "string" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "effective_at": { "anyOf": [ { "description": "Ora di entrata in vigore della modifica notificata oppure null.", "format": "date-time", "type": "string" }, { "description": "Ora di entrata in vigore della modifica notificata oppure null.", "type": "null" } ], "description": "Ora di entrata in vigore della modifica notificata oppure null." }, "emailed_at": { "anyOf": [ { "description": "Timestamp di consegna dell'email dell'avviso oppure null.", "format": "date-time", "type": "string" }, { "description": "Timestamp di consegna dell'email dell'avviso oppure null.", "type": "null" } ], "description": "Timestamp di consegna dell'email dell'avviso oppure null." }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "kind": { "description": "Identificativo della categoria del movimento contabile o dell'avviso.", "type": "string" }, "read_at": { "anyOf": [ { "description": "Timestamp di lettura dell'avviso oppure null.", "format": "date-time", "type": "string" }, { "description": "Timestamp di lettura dell'avviso oppure null.", "type": "null" } ], "description": "Timestamp di lettura dell'avviso oppure null." }, "reference": { "description": "Riferimento applicativo correlato usato per il tracciamento.", "type": "string" }, "title": { "description": "Titolo dell'avviso di servizio.", "type": "string" } }, "required": [], "type": "object" }, "CommerceNoticeList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/CommerceNotice" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "CommercePolicy": { "additionalProperties": false, "properties": { "documents": { "properties": { "privacy": { "type": "string" }, "refunds": { "type": "string" }, "terms": { "type": "string" } }, "type": "object" }, "locale": { "type": "string" }, "pending": { "items": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "effective_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "profile": { "$ref": "#/components/schemas/OperatorProfile" }, "published": { "type": "boolean" }, "ready": { "type": "boolean" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "CommercePolicyInput": { "additionalProperties": false, "properties": { "expected_version": { "type": "string" }, "profile": { "$ref": "#/components/schemas/OperatorProfile" }, "published": { "type": "boolean" } }, "required": [ "profile", "published", "expected_version" ], "type": "object" }, "CommerceResult": { "additionalProperties": true, "type": "object" }, "Confirmation": { "additionalProperties": false, "properties": { "confirm": { "const": true, "type": "boolean" } }, "required": [ "confirm" ], "type": "object" }, "Consumption": { "additionalProperties": false, "properties": { "feature": { "description": "Identificativo della funzionalità consumata.", "type": "string" }, "limit": { "description": "Limite di utilizzo delle funzionalità per questo periodo di quota.", "type": "integer" }, "overage": { "description": "Unità sopra il limite in questo periodo, non denaro. La policy controlla il limite di eccedenza delle funzionalità.", "type": "integer" }, "period": { "description": "Periodo di misurazione: YYYY-MM per quello mensile, YYYY-MM-DD per quello giornaliero, lifetime per il totale. I confini giornalieri/mensili usano UTC.", "type": "string" }, "quantity": { "description": "Unità richieste per questa operazione, numero intero 1–1000000000.", "type": "integer" }, "remaining": { "description": "remaining = max(0, limit - used - reserved), escluse le unità eccedenti.", "type": "integer" }, "reserved": { "description": "Unità riservate non scadute in questo periodo, non ancora addebitate.", "type": "integer" }, "reset_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Prossimo azzeramento, UTC ISO 8601; null per la misurazione lifetime." }, "used": { "description": "Unità confermate in questo periodo, escluse le prenotazioni.", "type": "integer" } }, "required": [], "type": "object" }, "ConsumptionResult": { "additionalProperties": false, "properties": { "activation_id": { "description": "UUID dell'associazione del dispositivo o della sessione di esecuzione. Conservarlo per le future richieste di licenza; non è una chiave di licenza.", "format": "uuid", "type": "string" }, "consumption": { "$ref": "#/components/schemas/Consumption" }, "heartbeat_seconds": { "anyOf": [ { "const": 0 }, { "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Intervallo corrente dell'heartbeat in secondi; la misurazione non aggiorna la firma né il timer.", "type": "integer" } }, "required": [ "activation_id", "consumption" ], "type": "object" }, "CustomerAssignment": { "additionalProperties": false, "properties": { "email": { "description": "Un valore vuoto rimuove il collegamento al portale", "type": "string" }, "name": { "description": "Nome leggibile dall'utente; consultare i vincoli di lunghezza.", "maxLength": 120, "type": "string" } }, "required": [ "email" ], "type": "object" }, "CustomerControlsInput": { "additionalProperties": false, "anyOf": [ { "required": [ "device_enabled" ] }, { "required": [ "api_enabled" ] } ], "properties": { "api_enabled": { "type": "boolean" }, "device_enabled": { "type": "boolean" } }, "required": [], "type": "object" }, "CustomerControlsResult": { "additionalProperties": false, "properties": { "api_enabled": { "type": "boolean" }, "device_enabled": { "type": "boolean" } }, "required": [ "device_enabled", "api_enabled" ], "type": "object" }, "CustomerDataExportInput": { "additionalProperties": false, "properties": { "current_password": { "type": "string" }, "reason": { "maxLength": 500, "type": "string" }, "scope": { "enum": [ "account", "workspace" ], "type": "string" } }, "required": [ "scope", "current_password", "reason" ], "type": "object" }, "CustomerLicenses": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } }, "required": [ "email", "items" ], "type": "object" }, "CustomerOverageConsent": { "additionalProperties": false, "properties": { "overage_accepted": { "description": "Autorizzazione esplicita separata degli sforamenti a pagamento visualizzati.", "type": "boolean" }, "policy_version": { "description": "Versione immutabile della politica attualmente pubblicata. Obbligatoria per le azioni protette dal consenso dopo che l'operatore ha pubblicato una politica, in entrambi gli ambienti di pagamento.", "type": "string" }, "price_version": { "type": "string" }, "terms_accepted": { "description": "Accettazione esplicita, non preselezionata per impostazione predefinita.", "type": "boolean" } }, "required": [ "price_version", "policy_version", "terms_accepted", "overage_accepted" ], "type": "object" }, "CustomerRefundInput": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "change_id": { "type": "string" }, "confirm_termination": { "type": "boolean" }, "incident_id": { "type": "string" }, "message": { "type": "string" }, "order_id": { "type": "string" }, "purchase_id": { "type": "string" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "reason": { "enum": [ "customer_request", "future", "wallet", "usage_change", "platform_failure", "statutory", "billing_error", "failed_delivery" ], "type": "string" }, "request_id": { "type": "string" }, "scope": { "description": "Un ambito esplicito prevede l'annullamento al momento dell'approvazione; l'omissione consente l'annullamento immediato, se idoneo, dopo una conferma esplicita.", "enum": [ "purchase", "service" ], "type": "string" } }, "required": [ "reason", "message", "request_id" ], "type": "object" }, "CustomerRefundQuote": { "anyOf": [ { "$ref": "#/components/schemas/RefundQuote" }, { "$ref": "#/components/schemas/ScopedRefundPreview" } ] }, "CustomerRefundQuoteInput": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "change_id": { "type": "string" }, "confirm_termination": { "type": "boolean" }, "incident_id": { "type": "string" }, "message": { "type": "string" }, "order_id": { "type": "string" }, "purchase_id": { "type": "string" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "reason": { "enum": [ "customer_request", "future", "wallet", "usage_change", "platform_failure", "statutory", "billing_error", "failed_delivery" ], "type": "string" }, "request_id": { "type": "string" }, "scope": { "description": "Un ambito esplicito prevede l'annullamento al momento dell'approvazione; l'omissione consente l'annullamento immediato, se idoneo, dopo una conferma esplicita.", "enum": [ "purchase", "service" ], "type": "string" } }, "required": [ "reason", "message" ], "type": "object" }, "CustomerReleaseInput": { "additionalProperties": false, "description": "Confermare il rilascio prima dell'invio. send_email accoda facoltativamente il codice temporaneo all'indirizzo verificato del cliente; generation protegge da una vista obsoleta del dispositivo.", "properties": { "generation": { "minimum": 1, "type": "integer" }, "send_email": { "type": "boolean" } }, "required": [], "type": "object" }, "CustomerReleaseResult": { "additionalProperties": false, "properties": { "email_queued": { "type": "boolean" }, "id": { "format": "uuid", "type": "string" }, "status": { "const": "released", "type": "string" }, "transfer": { "anyOf": [ { "$ref": "#/components/schemas/TransferCode" }, { "type": "null" } ] } }, "required": [ "id", "status", "transfer", "email_queued" ], "type": "object" }, "CustomerSession": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" } }, "required": [], "type": "object" }, "DatabaseStatus": { "additionalProperties": false, "properties": { "connected": { "type": "boolean" }, "database": { "type": "string" }, "host": { "type": "string" }, "open_connections": { "type": "integer" }, "version": { "type": "string" } }, "required": [ "connected", "host", "database" ], "type": "object" }, "DefaultPlan": { "additionalProperties": false, "properties": { "allow_customer_api_overage": { "default": false, "description": "Consente soltanto le scelte del cliente sugli sforamenti delle API. Indipendente dal permesso relativo ai dispositivi. Quando è false, l'utilizzo delle API segue le regole dell'amministratore. Le API illimitate rimangono illimitate.", "type": "boolean" }, "allow_customer_device_overage": { "default": false, "description": "Consente soltanto le scelte del cliente sugli sforamenti dei dispositivi. Quando è false, l'utilizzo dei dispositivi segue le regole dell'amministratore e le scelte salvate del cliente sui dispositivi vengono ignorate fino alla riattivazione.", "type": "boolean" }, "default_currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "default_plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" } }, "required": [ "default_plan", "default_currency" ], "type": "object" }, "DeliveryList": { "additionalProperties": false, "properties": { "items": { "anyOf": [ { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "type": "array" }, { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "type": "null" } ], "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo." }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [], "type": "object" }, "DeviceProfile": { "additionalProperties": false, "properties": { "hardware_id": { "description": "SHA-256 dell'identità del prodotto e dell'hardware. Vuoto se non disponibile; le politiche che richiedono l'hardware lo rifiuteranno.", "type": "string" }, "platform": { "description": "Sistema operativo locale: windows, linux o darwin (macOS).", "enum": [ "windows", "linux", "darwin" ], "type": "string" }, "system_id": { "description": "SHA-256 dell'identità del prodotto e del sistema: 64 caratteri esadecimali minuscoli.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "version": { "const": 3, "description": "Versione del protocollo dell'impronta digitale del dispositivo, attualmente 3.", "type": "integer" }, "virtual_machine": { "description": "Valore booleano: indica se l'SDK rileva una macchina virtuale.", "type": "boolean" } }, "required": [ "version", "system_id", "hardware_id", "virtual_machine", "platform" ], "type": "object" }, "DeviceReleaseOperation": { "additionalProperties": false, "properties": { "activation_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "attempts": { "description": "Numero di tentativi di elaborazione falliti conservato da Licentivo.", "type": "integer" }, "available_at": { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, { "description": "Ora di completamento dell'operazione; omessa mentre è in sospeso.", "type": "null" } ], "description": "Ora di completamento dell'operazione; omessa mentre è in sospeso." }, "connection_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "created_at": { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, "error_code": { "description": "Motivo stabile di elaborazione o revisione; vuoto dopo il successo.", "type": "string" }, "expected_generation": { "description": "Generazione attesa dell'associazione del dispositivo, confrontata all'interno della transazione di revoca.", "minimum": 1, "type": "integer" }, "license_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "operation_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "source": { "description": "Origine di questa operazione di revoca.", "enum": [ "logout", "launch", "admin" ], "type": "string" }, "status": { "description": "Stato corrente del ciclo di vita o dell'elaborazione, gestito dal server.", "enum": [ "pending", "succeeded", "stale", "manual_review" ], "type": "string" } }, "required": [ "operation_id", "license_id", "activation_id", "expected_generation", "source", "status" ], "type": "object" }, "EligibleReleases": { "additionalProperties": false, "properties": { "authorization": { "additionalProperties": true, "type": "object" }, "items": { "items": { "$ref": "#/components/schemas/Release" }, "type": "array" } }, "required": [], "type": "object" }, "Email": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" } }, "required": [ "email" ], "type": "object" }, "EmailChangeConfirmation": { "additionalProperties": false, "properties": { "token": { "maxLength": 2048, "minLength": 32, "type": "string" } }, "required": [ "token" ], "type": "object" }, "Empty": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "EmptyRefundPreviewInput": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "Error": { "additionalProperties": false, "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "properties": { "error": { "additionalProperties": false, "description": "Oggetto di errore o categoria di errore di consegna; consultare i campi subordinati o il tipo corrente.", "properties": { "code": { "description": "Codice di errore stabile leggibile dalla macchina.", "type": "string" }, "message": { "description": "Messaggio di errore leggibile dall'utente; per le diramazioni della logica usare invece code.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "UUID della richiesta HTTP generato dal server per la ricerca nei log; non è un ID di licenza né un ID di idempotenza.", "format": "uuid", "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "FeatureReservation": { "additionalProperties": false, "properties": { "consumption": { "$ref": "#/components/schemas/Consumption", "description": "Ricevuta di utilizzo: unità detratte, utilizzo cumulativo, quota rimanente e prossimo azzeramento." }, "expires_at": { "description": "Scadenza della prenotazione in UTC; confermare prima di questo orario.", "format": "date-time", "type": "string" }, "operation_id": { "description": "ID originale dell'attività usato per la prenotazione; conservarlo per i tentativi successivi.", "type": "string" }, "reservation_id": { "description": "ID della prenotazione; invia questo valore per confermare o annullare.", "format": "uuid", "type": "string" }, "status": { "description": "pending: eseguire l'operazione; committed: addebitata; canceled ed expired: chiusa senza addebito.", "enum": [ "pending", "committed", "canceled", "expired" ], "type": "string" } }, "required": [ "reservation_id", "operation_id", "status", "expires_at", "consumption" ], "type": "object" }, "FeatureUsage": { "additionalProperties": false, "properties": { "feature": { "description": "Identificativo di una funzionalità a consumo, che deve esistere nelle funzionalità della politica.", "type": "string" }, "license_id": { "description": "UUID della licenza, distinto dal segreto lv_lic_.", "format": "uuid", "type": "string" }, "period": { "description": "Istantanea di fatturazione mensile UTC predefinita; le regole di misurazione usano month/day/lifetime e le righe di utilizzo usano la chiave concreta del periodo.", "type": "string" }, "quantity": { "description": "Quantità cumulativa usata per questa funzionalità e questo periodo.", "type": "integer" }, "updated_at": { "description": "Timestamp dell'ultimo aggiornamento in UTC.", "format": "date-time", "type": "string" } }, "required": [ "license_id", "feature", "period", "quantity", "updated_at" ], "type": "object" }, "ForumAuthor": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "ForumImage": { "additionalProperties": false, "properties": { "height": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "size": { "type": "integer" }, "url": { "type": "string" }, "width": { "type": "integer" } }, "required": [ "id", "url", "width", "height", "size" ], "type": "object" }, "ForumModerationInput": { "additionalProperties": false, "description": "Richiede una sessione browser di amministratore della piattaforma. Fornire almeno un campo; i campi omessi conservano i valori correnti. La messa in evidenza si applica ad argomenti pubblicati o nascosti e non ripristina contenuti eliminati.", "minProperties": 1, "properties": { "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "pinned": { "type": "boolean" } }, "required": [], "type": "object" }, "ForumReply": { "additionalProperties": false, "properties": { "author": { "$ref": "#/components/schemas/ForumAuthor" }, "body": { "type": "string" }, "can_delete": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "images": { "items": { "$ref": "#/components/schemas/ForumImage" }, "type": "array" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "body", "author", "images", "created_at", "updated_at", "can_edit", "can_delete" ], "type": "object" }, "ForumReplyInput": { "additionalProperties": false, "properties": { "body": { "maxLength": 12000, "minLength": 1, "type": "string" }, "image_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 6, "type": "array", "uniqueItems": true } }, "required": [ "body" ], "type": "object" }, "ForumTopic": { "additionalProperties": false, "properties": { "author": { "$ref": "#/components/schemas/ForumAuthor" }, "body": { "type": "string" }, "can_delete": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_moderate": { "type": "boolean" }, "category": { "enum": [ "integration", "help", "ideas", "showcase" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "images": { "items": { "$ref": "#/components/schemas/ForumImage" }, "type": "array" }, "language": { "enum": [ "en", "zh", "zh-hant", "hi", "es", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "last_reply_at": { "format": "date-time", "type": "string" }, "locked": { "type": "boolean" }, "pinned": { "type": "boolean" }, "reply_count": { "type": "integer" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "title", "body", "category", "language", "locked", "pinned", "author", "images", "reply_count", "created_at", "updated_at", "last_reply_at", "can_edit", "can_delete", "can_moderate" ], "type": "object" }, "ForumTopicDetail": { "additionalProperties": false, "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "replies": { "items": { "$ref": "#/components/schemas/ForumReply" }, "type": "array" }, "topic": { "$ref": "#/components/schemas/ForumTopic" }, "total": { "type": "integer" } }, "required": [ "topic", "replies", "total", "limit", "offset" ], "type": "object" }, "ForumTopicInput": { "additionalProperties": false, "properties": { "body": { "maxLength": 12000, "minLength": 1, "type": "string" }, "category": { "enum": [ "integration", "help", "ideas", "showcase" ], "type": "string" }, "image_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 6, "type": "array", "uniqueItems": true }, "language": { "enum": [ "en", "zh", "zh-hant", "hi", "es", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "title": { "maxLength": 180, "minLength": 2, "type": "string" } }, "required": [ "title", "body", "category", "language" ], "type": "object" }, "ForumTopicList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ForumTopic" }, "type": "array" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "ForumTranslationInput": { "additionalProperties": false, "properties": { "reply_id": { "format": "uuid", "type": "string" }, "target_language": { "description": "Selezionare una lingua restituita da GET /forum/translation.", "type": "string" } }, "required": [ "target_language" ], "type": "object" }, "ForumTranslationResult": { "additionalProperties": false, "properties": { "body": { "description": "Testo semplice tradotto. Visualizzare con textContent, mai come HTML.", "type": "string" }, "cached": { "type": "boolean" }, "provider": { "type": "string" }, "source_language": { "description": "Lingua di origine rilevata e comunicata da DeepL.", "type": "string" }, "target_language": { "description": "Lingua di destinazione scelta del fornitore.", "type": "string" }, "title": { "description": "Titolo dell'argomento tradotto; vuoto per le risposte.", "type": "string" } }, "required": [ "title", "body", "source_language", "target_language", "cached", "provider" ], "type": "object" }, "Health": { "additionalProperties": false, "properties": { "status": { "enum": [ "ok", "ready" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "ID": { "additionalProperties": false, "properties": { "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "Invite": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" } }, "required": [ "email", "name", "role" ], "type": "object" }, "Invited": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "message": { "type": "string" } }, "required": [ "id", "message" ], "type": "object" }, "Invoice": { "additionalProperties": false, "properties": { "active_devices": { "description": "Numero di dispositivi congelato per la fatturazione a partire dal picco di occupazione del periodo predefinito. Non è l'occupazione corrente né un elenco cumulativo degli utilizzi dei dispositivi.", "type": "integer" }, "base_covered": { "description": "Indica se un pacchetto acquistato copre già l'addebito di base.", "type": "boolean" }, "base_micros": { "description": "Addebito di base in milionesimi dell'unità valutaria.", "type": "integer" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "finalized_at": { "anyOf": [ { "description": "Timestamp di finalizzazione della fattura oppure null.", "format": "date-time", "type": "string" }, { "description": "Timestamp di finalizzazione della fattura oppure null.", "type": "null" } ], "description": "Timestamp di finalizzazione della fattura oppure null." }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "included_devices": { "description": "Quota inclusa di dispositivi attivi.", "type": "integer" }, "month": { "description": "Mese UTC YYYY-MM; i valori di query omessi usano il mese corrente. Le attività di fatturazione richiedono un mese concluso.", "type": "string" }, "overage_devices": { "description": "Dispositivi che superano la quota inclusa.", "type": "integer" }, "paid_at": { "anyOf": [ { "description": "Timestamp di pagamento della fattura oppure null.", "format": "date-time", "type": "string" }, { "description": "Timestamp di pagamento della fattura oppure null.", "type": "null" } ], "description": "Timestamp di pagamento della fattura oppure null." }, "payment_mode": { "description": "Ambiente di pagamento, sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "type": "string" }, "plan_name": { "description": "Nome visualizzato del piano.", "type": "string" }, "price_version": { "description": "Revisione del prezzo congelata; un input obsoleto può causare PLAN_VERSION_CONFLICT.", "type": "string" }, "refunded_at": { "anyOf": [ { "description": "Timestamp di rimborso della fattura oppure null.", "format": "date-time", "type": "string" }, { "description": "Timestamp di rimborso della fattura oppure null.", "type": "null" } ], "description": "Timestamp di rimborso della fattura oppure null." }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "draft", "finalized", "void" ], "type": "string" }, "total_cents": { "description": "Totale della fattura in centesimi; consultare paid_at per lo stato del pagamento.", "type": "integer" }, "total_micros": { "description": "Totale della fattura in milionesimi dell'unità valutaria.", "type": "integer" }, "unit_micros": { "description": "Prezzo per dispositivo attivo eccedente, in milionesimi.", "type": "integer" }, "voided_at": { "anyOf": [ { "description": "Timestamp di annullamento della fattura oppure null.", "format": "date-time", "type": "string" }, { "description": "Timestamp di annullamento della fattura oppure null.", "type": "null" } ], "description": "Timestamp di annullamento della fattura oppure null." } }, "required": [ "id", "month", "currency", "status", "total_cents" ], "type": "object" }, "InvoiceList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/Invoice" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "Key": { "additionalProperties": false, "properties": { "allow_http": { "description": "Consente a questa chiave di registrare o aggiornare le origini dei siti Launch HTTP, inclusi domini dei server di test, indirizzi IP privati e nomi host interni. Le richieste all’API Licentivo continuano a usare HTTPS.", "type": "boolean" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "expires_at": { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "name": { "description": "Nome leggibile dall'utente; consultare i vincoli di lunghezza.", "type": "string" }, "prefix": { "description": "Primi 14 caratteri della chiave amministrativa; solo per identificazione.", "type": "string" }, "revoked": { "description": "Indica se è revocata; controllare anche expires_at per la scadenza.", "type": "boolean" }, "scope": { "description": "read consente le letture; write consente letture e scritture. Le scritture richiedono inoltre un creatore Owner attivo.", "enum": [ "read", "write" ], "type": "string" } }, "required": [ "id", "prefix", "scope", "revoked", "allow_http" ], "type": "object" }, "KeyBundle": { "additionalProperties": false, "properties": { "keys": { "items": { "$ref": "#/components/schemas/SigningKey" }, "type": "array" }, "product_id": { "format": "uuid", "type": "string" }, "protocol": { "type": "string" }, "runtime_policy_source": { "const": "current_license_policy", "type": "string" } }, "required": [ "product_id", "keys" ], "type": "object" }, "KeyCreate": { "additionalProperties": false, "properties": { "allow_http": { "default": false, "description": "Consente a questa chiave di registrare o aggiornare le origini dei siti Launch HTTP, inclusi domini dei server di test, indirizzi IP privati e nomi host interni. Le richieste all’API Licentivo continuano a usare HTTPS.", "type": "boolean" }, "expires_days": { "description": "Giorni dalla creazione alla scadenza, 1–365.", "maximum": 365, "minimum": 1, "type": "integer" }, "name": { "description": "Nome leggibile dall'utente; consultare i vincoli di lunghezza.", "maxLength": 120, "minLength": 1, "type": "string" }, "scope": { "description": "read consente le letture; write consente letture e scritture. Le scritture richiedono inoltre un creatore Owner attivo.", "enum": [ "read", "write" ], "type": "string" } }, "required": [ "name", "scope", "expires_days" ], "type": "object" }, "KeyList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/Key" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [ "items" ], "type": "object" }, "KeyRotated": { "additionalProperties": false, "example": { "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", "prefix": "lv_api_BBBBBBB" }, "properties": { "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "key": { "description": "Full secret returned on creation or rotation. Owners may also view saved license keys on demand in a browser session. Store privately; the prefix cannot authenticate.", "type": "string" }, "prefix": { "description": "Primi 14 caratteri della chiave amministrativa; solo per identificazione.", "type": "string" } }, "required": [ "id", "key", "prefix" ], "type": "object" }, "KeySecret": { "additionalProperties": false, "example": { "expires_at": "2027-01-16T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "prefix": "lv_api_AAAAAAA" }, "properties": { "allow_http": { "description": "Consente a questa chiave di registrare o aggiornare le origini dei siti Launch HTTP, inclusi domini dei server di test, indirizzi IP privati e nomi host interni. Le richieste all’API Licentivo continuano a usare HTTPS.", "type": "boolean" }, "expires_at": { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "key": { "description": "Mostrata soltanto alla creazione/rotazione", "type": "string" }, "prefix": { "description": "Primi 14 caratteri della chiave amministrativa; solo per identificazione.", "type": "string" } }, "required": [ "id", "key", "prefix" ], "type": "object" }, "KeyUpdate": { "additionalProperties": false, "properties": { "allow_http": { "description": "Consente a questa chiave di registrare o aggiornare le origini dei siti Launch HTTP, inclusi domini dei server di test, indirizzi IP privati e nomi host interni. Le richieste all’API Licentivo continuano a usare HTTPS.", "type": "boolean" } }, "required": [ "allow_http" ], "type": "object" }, "KeyUpdated": { "additionalProperties": false, "properties": { "allow_http": { "description": "Consente a questa chiave di registrare o aggiornare le origini dei siti Launch HTTP, inclusi domini dei server di test, indirizzi IP privati e nomi host interni. Le richieste all’API Licentivo continuano a usare HTTPS.", "type": "boolean" }, "id": { "description": "Unique record identifier.", "format": "uuid", "type": "string" } }, "required": [ "id", "allow_http" ], "type": "object" }, "LaunchCommerceEvent": { "additionalProperties": false, "properties": { "account_ref": { "description": "Riferimento immutabile del diritto di acquisto, con distinzione tra maiuscole e minuscole.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "entitlement_ref": { "description": "Riferimento immutabile del diritto di acquisto, con distinzione tra maiuscole e minuscole.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "description": "Ambiente commerciale, fissato sia nella connessione sia nell'autorizzazione firmata.", "enum": [ "live", "sandbox" ], "type": "string" }, "event_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "launch_product_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "legacy_license_id": { "description": "Solo per entitlement.migrated. La licenza, la scadenza, le funzionalità e i record dei dispositivi esistenti vengono conservati; le vecchie chiavi e credenziali dei dispositivi perdono l'accesso in fase di esecuzione.", "format": "uuid", "type": "string" }, "plan_ref": { "description": "Riferimento immutabile del diritto di acquisto, con distinzione tra maiuscole e minuscole.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "type": { "description": "Tipo di evento commerciale con istantanea completa e versione.", "enum": [ "entitlement.created", "entitlement.renewed", "entitlement.upgraded", "entitlement.downgraded", "entitlement.refunded", "entitlement.suspended", "entitlement.expired", "entitlement.resumed", "entitlement.migrated" ], "type": "string" }, "valid_from": { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, "valid_until": { "anyOf": [ { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, { "description": "Scadenza assoluta dell'acquisto, UTC; null soltanto per una politica perpetual.", "type": "null" } ], "description": "Scadenza assoluta dell'acquisto, UTC; null soltanto per una politica perpetual." }, "version": { "description": "Versione monotona dell'istantanea completa per questo riferimento di diritto, non numero del tentativo di consegna.", "minimum": 1, "type": "integer" } }, "required": [ "event_id", "environment", "type", "entitlement_ref", "account_ref", "launch_product_id", "plan_ref", "version", "valid_from" ], "type": "object" }, "LaunchConnection": { "additionalProperties": false, "properties": { "audience": { "description": "Destinatario esatto previsto per le attestazioni di accesso Launch.", "type": "string" }, "created_at": { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, "enabled": { "description": "Indica se questa connessione di fiducia può autorizzare nuovi utilizzi in fase di esecuzione.", "type": "boolean" }, "environment": { "description": "Ambiente commerciale, fissato sia nella connessione sia nell'autorizzazione firmata.", "enum": [ "live", "sandbox" ], "type": "string" }, "heartbeat_seconds": { "description": "Intervallo di verifica online in secondi selezionato dal server.", "type": "integer" }, "id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "issuer": { "description": "Origine Launch attendibile esatta.", "type": "string" }, "offline_seconds": { "description": "Intervallo offline finito consentito in secondi; zero richiede la verifica online.", "type": "integer" }, "session_seconds": { "description": "Durata massima della sessione di autorizzazione in secondi.", "type": "integer" }, "updated_at": { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" } }, "required": [ "id", "issuer", "audience", "environment", "enabled" ], "type": "object" }, "LaunchConnectionInput": { "additionalProperties": false, "properties": { "audience": { "description": "Destinatario esatto previsto per le attestazioni di accesso Launch.", "maxLength": 255, "minLength": 1, "type": "string" }, "enabled": { "description": "Indica se questa connessione di fiducia può autorizzare nuovi utilizzi in fase di esecuzione.", "type": "boolean" }, "environment": { "description": "Ambiente commerciale, fissato sia nella connessione sia nell'autorizzazione firmata.", "enum": [ "live", "sandbox" ], "type": "string" }, "heartbeat_seconds": { "default": 600, "description": "Intervallo di verifica online in secondi selezionato dal server.", "maximum": 86400, "minimum": 600, "type": "integer" }, "issuer": { "description": "Origine Launch attendibile esatta, senza percorso o barra finale. HTTPS è il valore predefinito. HTTP richiede allow_http sulla chiave API che effettua questa richiesta; sono supportati IP privati e nomi host interni. Non viene effettuata alcuna richiesta di callback o di rilevamento verso questa origine.", "format": "uri", "type": "string" }, "offline_seconds": { "default": 0, "description": "0 richiede la verifica online. Una durata offline positiva deve essere almeno 3 × heartbeat_seconds. Le autorizzazioni account offline permanenti sono disabilitate.", "maximum": 86400, "minimum": 0, "type": "integer" }, "public_keys": { "additionalProperties": { "description": "Chiave pubblica Ed25519 canonica Base64URL fissata, 32 byte.", "type": "string" }, "description": "Insieme completo fissato di chiavi pubbliche Ed25519 Launch indicizzate per ID della chiave.", "maxProperties": 16, "minProperties": 1, "type": "object" }, "session_seconds": { "default": 86400, "description": "Almeno 3 × heartbeat_seconds.", "maximum": 2592000, "minimum": 1800, "type": "integer" } }, "required": [ "issuer", "audience", "environment", "public_keys", "enabled" ], "type": "object" }, "LaunchDeviceReleaseInput": { "additionalProperties": false, "properties": { "account_ref": { "description": "Riferimento immutabile del diritto di acquisto, con distinzione tra maiuscole e minuscole.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "entitlement_ref": { "description": "Riferimento immutabile del diritto di acquisto, con distinzione tra maiuscole e minuscole.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "description": "Ambiente commerciale, fissato sia nella connessione sia nell'autorizzazione firmata.", "enum": [ "live", "sandbox" ], "type": "string" }, "expected_generation": { "description": "Generazione attesa dell'associazione del dispositivo, confrontata all'interno della transazione di revoca.", "minimum": 1, "type": "integer" }, "operation_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } }, "required": [ "operation_id", "account_ref", "entitlement_ref", "environment", "expected_generation" ], "type": "object" }, "LaunchEvent": { "additionalProperties": false, "properties": { "applied_at": { "anyOf": [ { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, { "description": "Ora in cui l'istantanea è stata applicata o classificata come obsoleta.", "type": "null" } ], "description": "Ora in cui l'istantanea è stata applicata o classificata come obsoleta." }, "attempts": { "description": "Numero di tentativi di elaborazione falliti conservato da Licentivo.", "type": "integer" }, "available_at": { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, "connection_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "created_at": { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, "error_code": { "description": "Motivo stabile di elaborazione o revisione; vuoto dopo il successo.", "type": "string" }, "event_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "status": { "description": "Stato corrente del ciclo di vita o dell'elaborazione, gestito dal server.", "enum": [ "pending", "applied", "stale", "manual_review" ], "type": "string" } }, "required": [ "connection_id", "event_id", "status", "attempts", "available_at" ], "type": "object" }, "LaunchExchangeInput": { "additionalProperties": false, "properties": { "activation_id": { "description": "data.activation_id dall'ultima attivazione riuscita. Obbligatorio per convalida, heartbeat, consume e disattivazione; omettere soltanto al primo activate.", "format": "uuid", "type": "string" }, "app_version": { "description": "Versione corrente dell'app, major.minor.patch, ad es. 1.0.0. Obbligatorio per la manutenzione o le regole sull'intervallo di versioni. Non segnalare erroneamente un'app più recente come una versione precedente.", "pattern": "^$|^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "device_id": { "description": "Hash SHA-256 di 64 caratteri esadecimali minuscoli, calcolato dall'SDK a partire dalle identità di prodotto, sistema e hardware. Non sostituirlo con un valore fisso.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "device_name": { "description": "Nome visualizzato nel dashboard, fino a 120 caratteri. Non determina l'identità del dispositivo.", "maxLength": 120, "type": "string" }, "device_profile": { "$ref": "#/components/schemas/DeviceProfile", "description": "Profilo della macchina generato dall'SDK. Fornirlo secondo i requisiti delle politiche per l'identità hardware, il rifiuto delle VM o la migrazione hardware." }, "environment": { "description": "Ambiente commerciale, fissato sia nella connessione sia nell'autorizzazione firmata.", "enum": [ "live", "sandbox" ], "type": "string" }, "feature": { "description": "Identificativo della funzionalità consumata.", "maxLength": 64, "type": "string" }, "identity_token": { "description": "JWT di identità Launch Ed25519 tipizzato e monouso; nessuna dichiarazione sui diritti viene considerata attendibile come diritto di acquisto.", "maxLength": 12288, "type": "string", "writeOnly": true }, "launch_connection_id": { "description": "ID della connessione Launch per questa operazione di autorizzazione Launch.", "format": "uuid", "type": "string" }, "license_key": { "const": "", "description": "Omettere o lasciare vuoto. Lo scambio dell'account non usa mai una chiave di licenza a lungo termine.", "type": "string" }, "product_id": { "description": "UUID del prodotto; deve corrispondere al prodotto della licenza.", "format": "uuid", "type": "string" }, "quantity": { "description": "Unità richieste per questa operazione, numero intero 1–1000000000.", "maximum": 1000000000, "minimum": 1, "type": "integer" }, "request_logout_ticket": { "description": "Negoziazione delle funzionalità dell'SDK. Richiedere un ticket di disconnessione riservato allo scollegamento quando non è conservato alcun ticket per l'associazione corrente. Ometterlo quando è già conservato un ticket di disconnessione valido; gli heartbeat a regime evitano una ricerca aggiuntiva del ticket.", "type": "boolean" }, "reservation_id": { "description": "ID della prenotazione; invia questo valore per confermare o annullare.", "format": "uuid", "type": "string" }, "reservation_seconds": { "default": 900, "description": "Durata facoltativa della prenotazione, 30–3600 secondi; valore predefinito 900. Termina prima se interviene l'azzeramento del periodo.", "maximum": 3600, "minimum": 30, "type": "integer" }, "session_id": { "description": "Obbligatorio per le licenze flottanti: generare un UUID per ogni istanza in esecuzione e riutilizzarlo nelle richieste di quell'istanza. Facoltativo per le licenze vincolate al dispositivo.", "format": "uuid", "type": "string" } }, "required": [ "product_id", "device_id", "identity_token", "launch_connection_id", "environment" ], "type": "object" }, "LaunchPlanMappingInput": { "additionalProperties": false, "properties": { "launch_product_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "policy_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "policy_version": { "description": "Versione corrente attesa della politica di autorizzazione mappata.", "minimum": 1, "type": "integer" }, "product_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } }, "required": [ "launch_product_id", "product_id", "policy_id", "policy_version" ], "type": "object" }, "LaunchSessionRevocation": { "additionalProperties": false, "properties": { "account_ref": { "description": "Riferimento immutabile del diritto di acquisto, con distinzione tra maiuscole e minuscole.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "completed_at": { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, "connection_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "created_at": { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, "environment": { "description": "Ambiente commerciale, fissato sia nella connessione sia nell'autorizzazione firmata.", "enum": [ "live", "sandbox" ], "type": "string" }, "event_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "reason": { "description": "Motivo di controllo facoltativo; un valore vuoto equivale all'omissione. forced_logout richiede l'ambito session; password_changed e account_disabled richiedono l'ambito account.", "enum": [ "", "forced_logout", "password_changed", "account_disabled" ], "type": "string" }, "released_devices": { "description": "Generazioni correnti delle associazioni dei dispositivi rilasciate; gli accessi più recenti vengono conservati.", "minimum": 0, "type": "integer" }, "revoked_before": { "description": "Presente per l'ambito account. Le nuove autenticazioni devono avere auth_time strettamente maggiore di questa soglia UTC, confrontata con precisione al secondo Unix. I valori sid già noti rimangono revocati permanentemente.", "format": "date-time", "type": "string" }, "revoked_credentials": { "description": "Credenziali dei dispositivi appena revocate dall'evento originale.", "minimum": 0, "type": "integer" }, "revoked_sessions": { "description": "Sessioni di autorizzazione appena revocate dall'evento originale.", "minimum": 0, "type": "integer" }, "scope": { "description": "session revoca un singolo sid Launch in tutti i prodotti e dispositivi di questa connessione; account revoca tutte le sessioni esistenti dell'account e rifiuta le vecchie attestazioni di autenticazione.", "enum": [ "session", "account" ], "type": "string" }, "sid": { "description": "Obbligatorio e non vuoto per l'ambito session; omettere o lasciare vuoto per l'ambito account. È il sid di accesso Launch, non una sessione di autorizzazione Licentivo né un ID di dispositivo.", "pattern": "^[A-Za-z0-9_-]{0,128}$", "type": "string" }, "status": { "const": "succeeded", "description": "Stato corrente del ciclo di vita o dell'elaborazione, gestito dal server.", "type": "string" } }, "required": [ "connection_id", "event_id", "environment", "account_ref", "scope", "status", "revoked_sessions", "revoked_credentials", "released_devices", "created_at", "completed_at" ], "type": "object" }, "LaunchSessionRevocationInput": { "additionalProperties": false, "oneOf": [ { "properties": { "reason": { "enum": [ "", "forced_logout" ] }, "scope": { "const": "session" }, "sid": { "description": "Riferimento immutabile del diritto di acquisto, con distinzione tra maiuscole e minuscole.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sid" ] }, { "properties": { "reason": { "enum": [ "", "password_changed", "account_disabled" ] }, "scope": { "const": "account" }, "sid": { "const": "" } } } ], "properties": { "account_ref": { "description": "Riferimento immutabile del diritto di acquisto, con distinzione tra maiuscole e minuscole.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "description": "Verifica di coerenza facoltativa. Omettere o lasciare vuoto per usare l'ambiente della connessione; un valore non vuoto deve corrispondere. Questo campo non modifica la fatturazione né fornisce test gratuiti dell'autorizzazione.", "enum": [ "", "live", "sandbox" ], "type": "string" }, "event_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "reason": { "description": "Motivo di controllo facoltativo; un valore vuoto equivale all'omissione. forced_logout richiede l'ambito session; password_changed e account_disabled richiedono l'ambito account.", "enum": [ "", "forced_logout", "password_changed", "account_disabled" ], "type": "string" }, "scope": { "description": "session revoca un singolo sid Launch in tutti i prodotti e dispositivi di questa connessione; account revoca tutte le sessioni esistenti dell'account e rifiuta le vecchie attestazioni di autenticazione.", "enum": [ "session", "account" ], "type": "string" }, "sid": { "description": "Obbligatorio e non vuoto per l'ambito session; omettere o lasciare vuoto per l'ambito account. È il sid di accesso Launch, non una sessione di autorizzazione Licentivo né un ID di dispositivo.", "pattern": "^[A-Za-z0-9_-]{0,128}$", "type": "string" } }, "required": [ "event_id", "account_ref", "scope" ], "type": "object" }, "Lease": { "additionalProperties": false, "properties": { "key_id": { "description": "UUID della chiave pubblica di firma; deve essere presente nel trusted_keys del prodotto.", "format": "uuid", "type": "string" }, "payload": { "description": "Codifica Base64URL senza padding dei byte JSON originali della licenza. La decodifica serve soltanto alla lettura; la verifica della firma è obbligatoria.", "type": "string" }, "signature": { "description": "Firma Ed25519 in Base64URL. Verificare il testo LicenovaLease/v1, un carattere di nuova riga e i byte JSON originali del payload decodificato. Non riserializzare JSON. La firma decodificata è di 64 byte.", "type": "string" }, "version": { "const": 1, "description": "Versione del protocollo della struttura di firma, attualmente 1.", "type": "integer" } }, "required": [ "version", "key_id", "payload", "signature" ], "type": "object" }, "LeaseClaims": { "additionalProperties": false, "description": "Decodificare i byte originali del payload firmato. Senza runtime_policy il TTL è limitato a 86400 secondi; altrimenti applicare la politica firmata. Non considerare mai attendibile il payload senza verificare firma/contesto.", "properties": { "activation_id": { "format": "uuid", "type": "string" }, "capabilities": { "$ref": "#/components/schemas/SignedCapabilities" }, "device_id": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "expires_at": { "maximum": 253402300799, "type": "integer" }, "features": { "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "issued_at": { "type": "integer" }, "key_id": { "format": "uuid", "type": "string" }, "license_id": { "format": "uuid", "type": "string" }, "max_devices": { "maximum": 10000, "minimum": 1, "type": "integer" }, "mode": { "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "offline_request_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "runtime_policy": { "$ref": "#/components/schemas/RuntimePolicy" }, "tenant_id": { "format": "uuid", "type": "string" }, "version": { "const": 1, "type": "integer" } }, "required": [], "type": "object" }, "LegalAcceptance": { "additionalProperties": false, "properties": { "accepted_at": { "format": "date-time", "type": "string" }, "api_overage_accepted": { "type": "boolean" }, "device_overage_accepted": { "type": "boolean" }, "digest": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "type": "string" }, "overage_accepted": { "type": "boolean" }, "price_version": { "type": "string" }, "reference": { "type": "string" }, "scope": { "type": "string" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "LegalAcceptanceList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/LegalAcceptance" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "LegalConsent": { "additionalProperties": false, "properties": { "overage_accepted": { "description": "Autorizzazione esplicita separata degli sforamenti a pagamento visualizzati.", "type": "boolean" }, "policy_version": { "description": "Versione immutabile della politica attualmente pubblicata. Obbligatoria per le azioni protette dal consenso dopo che l'operatore ha pubblicato una politica, in entrambi gli ambienti di pagamento.", "type": "string" }, "terms_accepted": { "description": "Accettazione esplicita, non preselezionata per impostazione predefinita.", "type": "boolean" } }, "required": [], "type": "object" }, "License": { "additionalProperties": false, "description": "La scadenza è null fino alla prima attivazione riuscita. La durata viene acquisita in un'istantanea all'emissione; la riattivazione non la azzera mai.", "example": { "created_at": "2026-10-18T00:00:00Z", "customer": "Order #1001", "duration_days": 30, "expires_at": null, "features": [ "export" ], "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key_prefix": "lv_lic_AAAAAAA", "max_devices": 1, "mode": "timed", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "properties": { "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "customer": { "description": "Etichetta del cliente definita dal fornitore, distinta dall'email del portale clienti.", "type": "string" }, "duration_days": { "description": "Giorni specifici della licenza dalla prima attivazione. Obbligatori 1–36500 per l'emissione timed/trial; assenti/null per perpetual. Non vengono mai memorizzati nella politica.", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "type": "null" } ], "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale." }, "features": { "description": "Fino a 32 identificatori distinti di funzionalità, ciascuno composto da 1–64 caratteri tra lettere ASCII, cifre, punti, trattini o trattini bassi.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "first_activated_at": { "anyOf": [ { "description": "Timestamp della prima attivazione riuscita; null prima dell'attivazione e invariato da rinnovi o trasferimenti.", "format": "date-time", "type": "string" }, { "description": "Timestamp della prima attivazione riuscita; null prima dell'attivazione e invariato da rinnovi o trasferimenti.", "type": "null" } ], "description": "Timestamp della prima attivazione riuscita; null prima dell'attivazione e invariato da rinnovi o trasferimenti." }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "key_prefix": { "description": "Prefisso breve della chiave di licenza per identificazione/ricerca, non per autenticazione.", "type": "string" }, "max_devices": { "description": "Numero massimo di dispositivi simultanei o posti flottanti per licenza.", "type": "integer" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "policy_id": { "description": "UUID della politica; deve appartenere al prodotto al momento dell'emissione.", "format": "uuid", "type": "string" }, "policy_version": { "description": "Revisione della politica; inviare il valore corrente quando si modificano tutte le funzionalità per impedire scritture obsolete.", "type": "integer" }, "product_id": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "active", "expired", "suspended", "revoked" ], "type": "string" }, "updated_at": { "description": "Timestamp dell'ultimo aggiornamento in UTC.", "format": "date-time", "type": "string" } }, "required": [ "id", "product_id", "key_prefix", "mode", "status" ], "type": "object" }, "LicenseCapabilities": { "additionalProperties": false, "example": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "properties": { "license_id": { "description": "UUID della licenza, distinto dal segreto lv_lic_.", "format": "uuid", "type": "string" }, "license_model": { "description": "Associazione del dispositivo node_locked o posti flottanti.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "Giorni di manutenzione dalla prima attivazione; 0 indica nessuna scadenza della manutenzione.", "type": "integer" }, "maintenance_until": { "anyOf": [ { "description": "Termine della manutenzione per le nuove release; può essere null prima dell'attivazione o quando illimitata.", "format": "date-time", "type": "string" }, { "description": "Termine della manutenzione per le nuove release; può essere null prima dell'attivazione o quando illimitata.", "type": "null" } ], "description": "Termine della manutenzione per le nuove release; può essere null prima dell'attivazione o quando illimitata." }, "max_version": { "description": "Versione massima consentita dell'applicazione; vuoto indica nessun limite superiore.", "type": "string" }, "min_version": { "description": "Versione minima consentita dell'applicazione; vuoto indica nessun limite inferiore.", "type": "string" }, "product_id": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" }, "updated_at": { "description": "Timestamp dell'ultimo aggiornamento in UTC.", "format": "date-time", "type": "string" } }, "required": [ "license_id", "product_id", "license_model", "maintenance_days", "maintenance_until", "min_version", "max_version", "updated_at" ], "type": "object" }, "LicenseCapabilityResult": { "additionalProperties": false, "example": { "customer_email": "buyer@example.com", "license": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "meter_rules": [], "usage": null }, "properties": { "customer_email": { "description": "Email associata del portale clienti; vuota quando non assegnata.", "type": "string" }, "license": { "$ref": "#/components/schemas/LicenseCapabilities", "description": "Istantanea delle funzionalità della licenza." }, "meter_rules": { "description": "Regole di misurazione delle funzionalità; vuoto indica che non ne è configurata alcuna.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Indica se sono consentiti utilizzi eccedenti della funzionalità.", "type": "boolean" }, "feature": { "description": "Identificativo di una funzionalità a consumo, che deve esistere nelle funzionalità della politica.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Utilizzi della funzionalità inclusi per periodo di misurazione (non un limite di paginazione).", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Utilizzo eccedente massimo consentito; disabilitato quando allow_overage è false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Istantanea di fatturazione mensile UTC predefinita; le regole di misurazione usano month/day/lifetime e le righe di utilizzo usano la chiave concreta del periodo.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "type": "array" }, "usage": { "anyOf": [ { "description": "Record effettivi di utilizzo delle funzionalità; possono essere null quando vuoti.", "items": { "$ref": "#/components/schemas/FeatureUsage" }, "type": "array" }, { "description": "Record effettivi di utilizzo delle funzionalità; possono essere null quando vuoti.", "type": "null" } ], "description": "Record effettivi di utilizzo delle funzionalità; possono essere null quando vuoti." } }, "required": [], "type": "object" }, "LicenseCreate": { "additionalProperties": false, "description": "Emette una licenza con il proprio duration_days. Le licenze timed/trial richiedono 1–36500 giorni; per le licenze perpetual il valore deve essere assente/null. Il tempo decorre dalla prima attivazione riuscita.", "properties": { "customer": { "description": "Nome del cliente o riferimento dell'ordine per la ricerca nel dashboard, fino a 254 caratteri.", "maxLength": 254, "type": "string" }, "customer_email": { "description": "Email associata del portale clienti; vuota quando non assegnata.", "format": "email", "maxLength": 254, "type": "string" }, "duration_days": { "description": "Durata della licenza in giorni, a partire dalla prima attivazione riuscita. Obbligatoria per l'emissione timed/trial; omettere o usare null per le licenze perpetual. Non viene mai ereditata dalla politica.", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "policy_id": { "description": "UUID di una politica di licenza appartenente a questo prodotto.", "format": "uuid", "type": "string" }, "product_id": { "description": "ID prodotto (UUID).", "format": "uuid", "type": "string" } }, "required": [ "product_id", "policy_id" ], "type": "object" }, "LicenseKeyReveal": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "key": { "description": "Original full license key, revealed only to a current Owner session.", "type": "string" }, "key_prefix": { "type": "string" } }, "required": [ "id", "key", "key_prefix" ], "type": "object" }, "LicenseList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/License" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "LicenseSecret": { "additionalProperties": false, "example": { "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "properties": { "duration_days": { "description": "Giorni di validità dalla prima attivazione; null per le licenze permanenti.", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "type": "null" } ], "description": "Scadenza finale della licenza, UTC ISO 8601; null prima della prima attivazione e per le licenze perpetue." }, "first_activated_at": { "anyOf": [ { "description": "Timestamp della prima attivazione riuscita; null prima dell'attivazione e invariato da rinnovi o trasferimenti.", "format": "date-time", "type": "string" }, { "description": "Timestamp della prima attivazione riuscita; null prima dell'attivazione e invariato da rinnovi o trasferimenti.", "type": "null" } ], "description": "Prima attivazione riuscita, UTC ISO 8601; null prima dell'attivazione. Il trasferimento del dispositivo non la reimposta." }, "id": { "description": "UUID del record della licenza per consultazioni amministrative, rinnovo o revoca. Non è una chiave di attivazione.", "format": "uuid", "type": "string" }, "key": { "description": "Chiave di licenza completa che inizia con lv_lic_. Mostrata una sola volta all'emissione; il fornitore deve conservarla privatamente e consegnarla al cliente.", "type": "string" }, "key_prefix": { "description": "Prefisso della chiave per l'identificazione nel pannello; non può attivare una licenza.", "type": "string" } }, "required": [ "id", "key", "key_prefix" ], "type": "object" }, "LicenseUpdate": { "additionalProperties": false, "properties": { "customer": { "description": "Etichetta del cliente definita dal fornitore, distinta dall'email del portale clienti.", "maxLength": 254, "type": "string" }, "features": { "description": "Fino a 32 identificatori distinti di funzionalità, ciascuno composto da 1–64 caratteri tra lettere ASCII, cifre, punti, trattini o trattini bassi.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "max_devices": { "description": "Numero massimo di dispositivi simultanei o posti flottanti per licenza.", "maximum": 10000, "minimum": 1, "type": "integer" }, "policy_id": { "description": "Passa questa licenza a una policy dello stesso prodotto. La modifica richiede un preview_token attuale; conserva la chiave di licenza, la durata originale e il consumo.", "format": "uuid", "type": "string" }, "preview_token": { "description": "Token restituito da POST /licenses/policy-preview per questa licenza e la policy di destinazione.", "type": "string" }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "active", "suspended", "revoked" ], "type": "string" } }, "required": [], "type": "object" }, "LicensingWebhook": { "additionalProperties": false, "properties": { "created_at": { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, "enabled": { "description": "Indica se HTTP è consentito, soltanto per lo sviluppo locale.", "type": "boolean" }, "events": { "description": "Tipi di evento sottoscritti non vuoti e distinti.", "items": { "enum": [ "license.created", "license.updated", "license.renewed", "license.revoked", "license.activate", "license.deactivate", "license.consume", "license.expiring", "license.expired", "license.maintenance_expiring", "license.maintenance_expired" ], "type": "string" }, "type": "array" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "name": { "description": "Nome leggibile dall'utente; consultare i vincoli di lunghezza.", "type": "string" }, "updated_at": { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, "url": { "description": "URL del destinatario degli eventi; usare HTTPS pubblico in produzione.", "type": "string" } }, "required": [ "id", "name", "url", "events", "enabled", "created_at", "updated_at" ], "type": "object" }, "LicensingWebhookInput": { "additionalProperties": false, "properties": { "enabled": { "description": "Indica se l'endpoint webhook è abilitato.", "type": "boolean" }, "events": { "description": "Tipi di evento sottoscritti non vuoti e distinti.", "items": { "enum": [ "license.created", "license.updated", "license.renewed", "license.revoked", "license.activate", "license.deactivate", "license.consume", "license.expiring", "license.expired", "license.maintenance_expiring", "license.maintenance_expired" ], "type": "string" }, "type": "array" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "name": { "description": "Nome leggibile dall'utente; consultare i vincoli di lunghezza.", "maxLength": 120, "type": "string" }, "secret": { "description": "Segreto di verifica del webhook, 32–200 caratteri quando fornito; ometterlo durante l'aggiornamento lo conserva. Un output vuoto indica che non è stato riemesso.", "maxLength": 200, "minLength": 32, "type": "string", "writeOnly": true }, "url": { "description": "URL del destinatario degli eventi; usare HTTPS pubblico in produzione.", "format": "uri", "maxLength": 2000, "type": "string" } }, "required": [ "name", "url", "events", "enabled" ], "type": "object" }, "LicensingWebhookList": { "additionalProperties": false, "properties": { "event_types": { "description": "Tutti i tipi di evento di licenza supportati.", "items": { "enum": [ "license.created", "license.updated", "license.renewed", "license.revoked", "license.activate", "license.deactivate", "license.consume", "license.expiring", "license.expired", "license.maintenance_expiring", "license.maintenance_expired" ], "type": "string" }, "type": "array" }, "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/LicensingWebhook" }, "type": "array" } }, "required": [], "type": "object" }, "LicensingWebhookSecret": { "additionalProperties": false, "properties": { "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "secret": { "description": "Restituito una sola volta per i nuovi endpoint; vuoto quando conservato", "type": "string" } }, "required": [], "type": "object" }, "LoggedOut": { "additionalProperties": false, "properties": { "logged_out": { "type": "boolean" } }, "required": [ "logged_out" ], "type": "object" }, "Login": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "password": { "description": "12–128 byte UTF-8, non caratteri", "type": "string", "writeOnly": true } }, "required": [ "email", "password" ], "type": "object" }, "LogoutTicket": { "additionalProperties": false, "properties": { "activation_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "expected_generation": { "description": "Generazione attesa dell'associazione del dispositivo, confrontata all'interno della transazione di revoca.", "minimum": 1, "type": "integer" }, "operation_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "product_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "release_token": { "description": "Facoltà riservata allo scollegamento. Non può attivare, convalidare, aggiornare né consumare funzionalità. Conservarla soltanto nel registro di disconnessione dell'SDK mentre la revoca è in sospeso.", "pattern": "^lv_out_[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": [ "operation_id", "product_id", "activation_id", "expected_generation", "release_token" ], "type": "object" }, "MailConnection": { "additionalProperties": false, "properties": { "check_status": { "enum": [ "verified", "limited" ], "type": "string" }, "delivery_mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "message": { "type": "string" }, "mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "ok": { "description": "False per una verifica limitata: le credenziali e la consegna non sono state confermate.", "type": "boolean" }, "status": { "enum": [ "connected" ], "type": "string" } }, "required": [ "status", "mode", "delivery_mode", "ok", "check_status" ], "type": "object" }, "MailInput": { "additionalProperties": false, "description": "Aggiornamento parziale delle impostazioni email cifrate della piattaforma. I campi omessi e le configurazioni degli altri fornitori vengono conservati; chiavi API e password SMTP vuote mantengono i segreti esistenti. Il servizio attivo selezionato deve essere completamente configurato. La modalità file non è disponibile in produzione. Richiede una sessione di amministratore della piattaforma e un token CSRF; le chiavi API amministrative dei fornitori non possono modificare le impostazioni email della piattaforma.", "properties": { "from": { "type": "string" }, "host": { "maxLength": 253, "type": "string" }, "mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "password": { "description": "Omettere o lasciare vuoto per conservare la password SMTP esistente.", "maxLength": 1000, "type": "string", "writeOnly": true }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" }, "providers": { "additionalProperties": false, "properties": { "brevo": { "$ref": "#/components/schemas/MailProviderInput" }, "mailgun": { "$ref": "#/components/schemas/MailgunInput" }, "postmark": { "$ref": "#/components/schemas/MailProviderInput" }, "resend": { "$ref": "#/components/schemas/MailProviderInput" } }, "required": [], "type": "object" }, "tls_mode": { "enum": [ "starttls", "implicit" ], "type": "string" }, "username": { "maxLength": 254, "type": "string" } }, "required": [], "type": "object" }, "MailJob": { "additionalProperties": false, "properties": { "attempts": { "type": "integer" }, "cancel_reason": { "enum": [ "", "platform_disabled", "customer_disabled", "coverage_changed", "reminder_window_changed", "renewal_state_changed", "purchase_unavailable", "workspace_unavailable", "recipient_unavailable", "unknown_notification" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "delivered_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "", "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem", "billing_test" ], "type": "string" }, "mode": { "enum": [ "", "sandbox", "live" ], "type": "string" }, "recipient": { "type": "string" }, "status": { "enum": [ "pending", "running", "delivered", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "status", "attempts" ], "type": "object" }, "MailJobList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/MailJob" }, "maxItems": 50, "type": "array" } }, "required": [ "items" ], "type": "object" }, "MailProviderInput": { "additionalProperties": false, "properties": { "api_key": { "description": "Chiave API del fornitore; Postmark usa un Server API Token. Omettere o lasciare vuoto per conservare il segreto salvato.", "maxLength": 4096, "type": "string", "writeOnly": true }, "from": { "description": "Email del mittente verificata; obbligatoria quando si seleziona questo fornitore come attivo.", "type": "string" } }, "required": [], "type": "object" }, "MailProviderSettings": { "additionalProperties": false, "properties": { "api_key_configured": { "type": "boolean" }, "domain": { "description": "Dominio di invio Mailgun; vuoto per gli altri fornitori.", "type": "string" }, "from": { "type": "string" }, "region": { "description": "Regione Mailgun; vuota per gli altri fornitori.", "enum": [ "", "us", "eu" ], "type": "string" } }, "required": [ "from", "domain", "region", "api_key_configured" ], "type": "object" }, "MailQueued": { "additionalProperties": false, "properties": { "job_id": { "format": "uuid", "type": "string" }, "status": { "enum": [ "pending" ], "type": "string" } }, "required": [ "job_id", "status" ], "type": "object" }, "MailSettings": { "additionalProperties": false, "properties": { "from": { "type": "string" }, "host": { "type": "string" }, "mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "password_configured": { "type": "boolean" }, "port": { "type": "integer" }, "providers": { "additionalProperties": false, "properties": { "brevo": { "$ref": "#/components/schemas/MailProviderSettings" }, "mailgun": { "$ref": "#/components/schemas/MailProviderSettings" }, "postmark": { "$ref": "#/components/schemas/MailProviderSettings" }, "resend": { "$ref": "#/components/schemas/MailProviderSettings" } }, "required": [ "resend", "brevo", "postmark", "mailgun" ], "type": "object" }, "tls_mode": { "enum": [ "starttls", "implicit" ], "type": "string" }, "username": { "type": "string" } }, "required": [ "mode", "port", "password_configured", "providers" ], "type": "object" }, "MailgunInput": { "additionalProperties": false, "properties": { "api_key": { "description": "Chiave API dell'account Mailgun o chiave di invio del dominio. Omettere o lasciare vuoto per conservare il segreto salvato.", "maxLength": 4096, "type": "string", "writeOnly": true }, "domain": { "description": "Dominio di invio, obbligatorio quando Mailgun è attivo; senza schema, percorso o porta.", "maxLength": 253, "type": "string" }, "from": { "description": "Email del mittente verificata; obbligatoria quando Mailgun è attivo.", "type": "string" }, "region": { "default": "us", "description": "Regione che ospita il dominio di invio; US ed EU usano endpoint API fissi separati.", "enum": [ "us", "eu" ], "type": "string" } }, "required": [], "type": "object" }, "ManagementKeyBundle": { "additionalProperties": false, "properties": { "keys": { "description": "Chiavi pubbliche di firma correnti e storiche del prodotto.", "items": { "$ref": "#/components/schemas/SigningKey" }, "type": "array" }, "product_id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } }, "required": [ "product_id", "keys" ], "type": "object" }, "ManualRefundInput": { "additionalProperties": false, "properties": { "customer_agreement": { "maxLength": 3000, "type": "string" }, "evidence": { "maxLength": 3000, "type": "string" } }, "required": [ "customer_agreement", "evidence" ], "type": "object" }, "Me": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "is_platform_admin": { "type": "boolean" }, "name": { "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" } }, "required": [ "tenant_id", "id", "role", "is_platform_admin" ], "type": "object" }, "Member": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "is_platform_admin": { "type": "boolean" }, "name": { "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "verified": { "type": "boolean" } }, "required": [ "id", "role", "status", "verified" ], "type": "object" }, "MemberList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/Member" }, "type": "array" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "items" ], "type": "object" }, "MemberUpdate": { "additionalProperties": false, "properties": { "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" } }, "required": [], "type": "object" }, "MonthInput": { "additionalProperties": false, "properties": { "month": { "description": "Mese UTC YYYY-MM; i valori di query omessi usano il mese corrente. Le attività di fatturazione richiedono un mese concluso.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, "required": [ "month" ], "type": "object" }, "Notice": { "additionalProperties": false, "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" }, "OfflineReleaseResult": { "additionalProperties": false, "example": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "properties": { "activation_id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "deactivated": { "description": "Indica se HTTP è consentito, soltanto per lo sviluppo locale.", "type": "boolean" } }, "required": [ "activation_id", "deactivated" ], "type": "object" }, "OfflineRequest": { "additionalProperties": false, "properties": { "activation_id": { "description": "UUID del record di attivazione del dispositivo o della sessione flottante.", "format": "uuid", "type": "string" }, "app_version": { "description": "Vuoto per l'attivazione ordinaria. Fornire la versione effettivamente pubblicata dell'applicazione soltanto quando si usano restrizioni di versione o manutenzione.", "pattern": "^$|^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "type": "integer" }, "device_id": { "description": "L'SDK deriva l'identità del sistema operativo e dell'hardware specifica del prodotto usando LicenovaDevice/v3. La configurazione non può sostituire la macchina corrente.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "device_name": { "description": "Etichetta del dispositivo leggibile dall'utente, non un'identità di sicurezza.", "maxLength": 120, "type": "string" }, "device_profile": { "$ref": "#/components/schemas/DeviceProfile", "description": "Identità del dispositivo generata dall'SDK; quando presente, fornire tutti i campi subordinati obbligatori." }, "license_key": { "description": "Chiave di licenza originale; codice monouso lv_tmp_ soltanto per activate; successivamente una credenziale lv_dev_ vincolata alla macchina per le operazioni di esecuzione. L'SDK conserva le credenziali separatamente dai lease.", "pattern": "^lv_(lic|tmp|dev)_[A-Za-z0-9_-]{43}$", "type": "string", "writeOnly": true }, "operation": { "description": "Nome dell'operazione; i batch supportano create/renew/revoke/apply_policy e le richieste offline activate/deactivate.", "enum": [ "activate", "deactivate" ], "type": "string" }, "product_id": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" }, "session_id": { "description": "Identificativo della sessione di un'istanza flottante; può essere omesso per le licenze vincolate al dispositivo.", "format": "uuid", "type": "string" }, "version": { "const": 1, "description": "Revisione della politica, versione major.minor.patch del prodotto o versione 1 del protocollo offline, a seconda dell'oggetto.", "type": "integer" } }, "required": [ "version", "request_id", "created_at", "operation", "product_id", "license_key", "device_id" ], "type": "object" }, "OfflineResponse": { "additionalProperties": false, "example": { "operation": "deactivate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "version": 1 }, "properties": { "operation": { "description": "Nome dell'operazione; i batch supportano create/renew/revoke/apply_policy e le richieste offline activate/deactivate.", "enum": [ "activate", "deactivate" ], "type": "string" }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeResult", "description": "Risultato dell'operazione offline: l'attivazione restituisce un lease firmato; il rilascio restituisce deactivated." }, { "$ref": "#/components/schemas/OfflineReleaseResult", "description": "Risultato dell'operazione offline: l'attivazione restituisce un lease firmato; il rilascio restituisce deactivated." } ], "description": "Risultato dell'operazione offline: l'attivazione restituisce un lease firmato; il rilascio restituisce deactivated." }, "version": { "const": 1, "description": "Revisione della politica, versione major.minor.patch del prodotto o versione 1 del protocollo offline, a seconda dell'oggetto.", "type": "integer" } }, "required": [ "version", "request_id", "operation", "result" ], "type": "object" }, "OnboardingInput": { "additionalProperties": false, "properties": { "description": { "description": "Descrizione del prodotto; può essere vuota.", "maxLength": 1000, "type": "string" }, "duration_days": { "description": "Durata della sola licenza di test generata; valore predefinito 7 per timed/trial. Non viene salvata nella politica generata.", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "features": { "default": [ "export" ], "description": "Fino a 32 identificatori distinti di funzionalità, ciascuno composto da 1–64 caratteri tra lettere ASCII, cifre, punti, trattini o trattini bassi.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita." }, { "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "0 disabilita esplicitamente gli heartbeat periodici; altrimenti 600–86400 secondi (minimo 10 minuti). Indipendente dalla durata offline consentita.", "type": "integer" }, "license_model": { "default": "node_locked", "description": "Associazione del dispositivo node_locked o posti flottanti.", "enum": [ "node_locked", "floating" ], "type": "string" }, "max_devices": { "default": 1, "description": "Numero massimo di dispositivi simultanei o posti flottanti per licenza.", "maximum": 10000, "minimum": 1, "type": "integer" }, "mode": { "default": "trial", "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "Nome leggibile dall'utente; consultare i vincoli di lunghezza.", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "Durata offline consentita limited, none o permanent; la scadenza della licenza continua ad applicarsi.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Limited: 1–31536000 secondi e almeno 3 × heartbeat_seconds con gli heartbeat attivi; none/permanent: 0", "maximum": 31536000, "minimum": 0, "type": "integer" }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "request_id", "name" ], "type": "object" }, "OnboardingResult": { "additionalProperties": false, "example": { "config": { "allow_http": false, "app_version": "1.0.0", "base_url": "https://license.example.com", "cache_path": "", "device_name": "My application", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "product_id": "11111111-1111-4111-8111-111111111111", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "license_id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "next": "Choose a language and download the configured SDK bundle.", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "properties": { "config": { "$ref": "#/components/schemas/SDKConfig", "description": "Configurazione SDK privata di test contenente un segreto di licenza." }, "license_id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "license_key": { "description": "Chiave di licenza completa del cliente fornita all'attivazione. Il codice di inizializzazione del prodotto e gli esempi scaricabili non contengono questo segreto. Le richieste offline usano la credenziale fornita dall'SDK.", "type": "string" }, "next": { "description": "Piano predefinito programmato per il mese successivo oppure null.", "type": "string" }, "policy_id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "product_id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } }, "required": [ "product_id", "policy_id", "license_id", "license_key", "config", "next" ], "type": "object" }, "OperatorProfile": { "additionalProperties": false, "properties": { "backup_region": { "maxLength": 500, "type": "string" }, "contact": { "maxLength": 500, "type": "string" }, "country": { "maxLength": 500, "type": "string" }, "financial_retention_years": { "description": "Zero o omesso indica non confermato e non viene incluso nei documenti pubblici.", "maximum": 30, "minimum": 0, "type": "integer" }, "hosting_provider": { "maxLength": 500, "type": "string" }, "mail_provider": { "maxLength": 500, "type": "string" }, "markets": { "maxLength": 500, "type": "string" }, "operator": { "maxLength": 500, "type": "string" }, "processing_grounds": { "maxLength": 500, "type": "string" }, "server_region": { "maxLength": 500, "type": "string" }, "transfer_safeguards": { "maxLength": 500, "type": "string" } }, "required": [], "type": "object" }, "OriginalRefundInput": { "additionalProperties": false, "properties": { "amount": { "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "reason": { "maxLength": 255, "minLength": 1, "type": "string" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "amount", "reason", "request_id" ], "type": "object" }, "OriginalRefundResult": { "additionalProperties": false, "properties": { "case_id": { "format": "uuid", "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/ProviderRefund" }, "type": "array" } }, "type": "object" }, "OveragePlan": { "additionalProperties": false, "properties": { "api_hard_limit": { "description": "Indica se le chiamate di esecuzione si interrompono al raggiungimento della quota API.", "type": "boolean" }, "api_unit_micros": { "description": "Prezzo per chiamata di esecuzione eccedente, in milionesimi.", "minimum": 0, "type": "integer" }, "base_micros": { "description": "Addebito di base in milionesimi dell'unità valutaria.", "type": "integer" }, "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "type": "string" }, "description": { "description": "Descrizione dell'offerta di fatturazione.", "type": "string" }, "enabled": { "description": "Indica se l'offerta di fatturazione è abilitata all'acquisto.", "type": "boolean" }, "hard_limit": { "description": "Indica se i nuovi dispositivi fatturabili vengono rifiutati al raggiungimento della quota.", "type": "boolean" }, "included_api_calls": { "description": "null = illimitato; 0 = nessuna chiamata riuscita inclusa", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "description": "Quota inclusa di dispositivi attivi.", "type": "integer" }, "name": { "description": "Nome visualizzato dell'offerta di fatturazione.", "type": "string" }, "plan": { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "type": "string" }, "price_version": { "description": "Revisione del prezzo congelata; un input obsoleto può causare PLAN_VERSION_CONFLICT.", "type": "string" }, "public": { "description": "Indica se l'offerta di fatturazione è elencata pubblicamente.", "type": "boolean" }, "renewal_only": { "description": "I clienti esistenti con pacchetti pagati o regalati possono rinnovare in anticipo o dopo la scadenza nello stesso ambiente e nella stessa valuta. Nascosto dai nuovi acquisti pubblici.", "type": "boolean" }, "sort_order": { "description": "Ordine di visualizzazione dell'offerta di fatturazione.", "type": "integer" }, "terms": { "anyOf": [ { "description": "Durate di acquisto disponibili e relativi prezzi.", "items": { "$ref": "#/components/schemas/PlanTermPrice" }, "type": "array" }, { "description": "Durate di acquisto disponibili e relativi prezzi.", "type": "null" } ], "description": "Durate di acquisto disponibili e relativi prezzi." }, "unit_micros": { "description": "Prezzo per dispositivo attivo eccedente, in milionesimi.", "type": "integer" }, "updated_at": { "description": "Timestamp dell'ultimo aggiornamento in UTC.", "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "OveragePreference": { "additionalProperties": false, "properties": { "block_api_overage": { "description": "Indica se le chiamate API di esecuzione oltre la quota inclusa vengono bloccate.", "type": "boolean" }, "block_device_overage": { "description": "Indica se i nuovi dispositivi fatturabili oltre la quota inclusa vengono bloccati.", "type": "boolean" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" }, "updated_at": { "description": "Timestamp dell'ultimo aggiornamento in UTC.", "format": "date-time", "type": "string" }, "version": { "description": "Revisione della configurazione delle preferenze sugli sforamenti.", "type": "string" } }, "required": [ "mode", "block_device_overage", "block_api_overage", "version", "updated_at" ], "type": "object" }, "OverageSettings": { "additionalProperties": false, "properties": { "customer_api_settings_enabled": { "description": "Indica se i clienti possono configurare il blocco degli sforamenti API.", "type": "boolean" }, "customer_device_settings_enabled": { "description": "Indica se i clienti possono configurare il blocco degli sforamenti dei dispositivi.", "type": "boolean" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/OveragePlan", "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato." }, { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "type": "null" } ], "description": "Regole correnti della quota acquistata/predefinita usate per determinare gli sforamenti oppure null quando non disponibili." }, "preference": { "$ref": "#/components/schemas/OveragePreference", "description": "Preferenze salvate del cliente sugli sforamenti." } }, "required": [ "preference", "plan", "customer_device_settings_enabled", "customer_api_settings_enabled" ], "type": "object" }, "OverageSettingsInput": { "additionalProperties": false, "properties": { "block_api_overage": { "type": "boolean" }, "block_device_overage": { "type": "boolean" }, "expected_version": { "description": "Usare preference.version dalla richiesta GET. Vuoto al primo salvataggio. Le modifiche da un'altra scheda restituiscono 409; è richiesta almeno una scelta sugli sforamenti.", "type": "string" } }, "required": [ "expected_version" ], "type": "object" }, "PaddleCheck": { "additionalProperties": false, "properties": { "connected": { "description": "Indica se questo canale accetta nuovi checkout. La riconciliazione storica rimane disponibile con le credenziali conservate.", "type": "boolean" }, "mode": { "description": "Ambiente di pagamento. I record sandbox e live sono isolati.", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "connected", "mode" ], "type": "object" }, "PaddleOrder": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Prezzo completo del servizio congelato nell'unità monetaria minima; nessuna ricarica del portafoglio o pagamento misto.", "type": "integer" }, "applied_at": { "anyOf": [ { "description": "Ora UTC di salvataggio dell'intenzione di checkout locale.", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Ora UTC in cui il pagamento verificato ha attivato il servizio o accreditato una ricarica del portafoglio. purchase_id e upgrade_id null identificano una ricarica." }, "created_at": { "description": "Ora UTC di salvataggio dell'intenzione di checkout locale.", "format": "date-time", "type": "string" }, "currency": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" }, "mode": { "description": "Ambiente di pagamento. I record sandbox e live sono isolati.", "enum": [ "sandbox", "live" ], "type": "string" }, "paid_at": { "anyOf": [ { "description": "Ora UTC di salvataggio dell'intenzione di checkout locale.", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Ora UTC in cui il backend ha verificato una transazione Paddle completata." }, "purchase_id": { "anyOf": [ { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Acquisto di servizio o rinnovo esistente in sospeso; mutuamente esclusivo con upgrade_id." }, "refunded_cents": { "description": "Prezzo completo del servizio congelato nell'unità monetaria minima; nessuna ricarica del portafoglio o pagamento misto.", "type": "integer" }, "request_id": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "status": { "description": "Ciclo di vita del pagamento, incluso paid_unapplied quando i fondi incassati richiedono revisione e rimborso da parte dell'operatore.", "enum": [ "creating", "created", "completed", "paid_unapplied", "partially_refunded", "refunded" ], "type": "string" }, "transaction_id": { "anyOf": [ { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, { "type": "null" } ], "description": "Identificativo della transazione Paddle Billing associata oppure null mentre l'esito della creazione originale è in sospeso." }, "upgrade_id": { "anyOf": [ { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Preventivo di upgrade esistente in sospeso; mutuamente esclusivo con purchase_id." } }, "required": [ "id", "request_id", "mode", "transaction_id", "purchase_id", "upgrade_id", "currency", "amount_cents", "refunded_cents", "status", "paid_at", "applied_at", "created_at" ], "type": "object" }, "PaddleOrderInput": { "additionalProperties": false, "description": "Paga un singolo acquisto/upgrade congelato oppure crea una ricarica del portafoglio con amount e currency e senza ID di servizio. Un request_id stabile restituisce il pagamento originale; la modifica dell'intenzione, dell'importo o della valuta viene rifiutata. Solo i pagamenti completati e verificati indipendentemente accreditano un portafoglio o attivano il servizio. I ritorni delle ricariche portano al portafoglio. Un esito di creazione incerto viene recuperato dal webhook originale e non viene mai ricreato alla cieca.", "oneOf": [ { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "format": "uuid", "type": "string" }, "upgrade_id": { "type": "null" } }, "required": [ "purchase_id" ] }, { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "format": "uuid", "type": "string" } }, "required": [ "upgrade_id" ] }, { "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "type": "null" } }, "required": [ "amount", "currency" ] } ], "properties": { "amount": { "description": "Obbligatorio soltanto per una ricarica del portafoglio. Importo decimale visualizzato entro i limiti configurati. Gli ordini di servizio rifiutano gli importi forniti dal client.", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "type": "string" }, "currency": { "description": "Obbligatorio soltanto per una ricarica del portafoglio e deve essere abilitato per questo fornitore.", "type": "string" }, "overage_accepted": { "description": "Autorizzazione esplicita separata degli sforamenti a pagamento visualizzati.", "type": "boolean" }, "policy_version": { "description": "Versione immutabile della politica attualmente pubblicata. Obbligatoria per le azioni protette dal consenso dopo che l'operatore ha pubblicato una politica, in entrambi gli ambienti di pagamento.", "type": "string" }, "purchase_id": { "anyOf": [ { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Acquisto di servizio o rinnovo esistente in sospeso; mutuamente esclusivo con upgrade_id." }, "request_id": { "description": "Chiave di richiesta stabile generata dal chiamante. Le ripetizioni restituiscono il checkout originale.", "maxLength": 80, "type": "string" }, "terms_accepted": { "description": "Accettazione esplicita, non preselezionata per impostazione predefinita.", "type": "boolean" }, "upgrade_id": { "anyOf": [ { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Preventivo di upgrade esistente in sospeso; mutuamente esclusivo con purchase_id." } }, "required": [ "request_id" ], "type": "object" }, "PaddleOrderList": { "additionalProperties": false, "properties": { "items": { "description": "Record visibili a questo amministratore o spazio di lavoro.", "items": { "$ref": "#/components/schemas/PaddleOrder" }, "type": "array" }, "total": { "description": "Prezzo completo del servizio congelato nell'unità monetaria minima; nessuna ricarica del portafoglio o pagamento misto.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PaddleOrderResult": { "additionalProperties": false, "properties": { "approval_url": { "description": "Pagina di checkout locale che apre la transazione Paddle associata.", "format": "uri", "type": "string" }, "client_token": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "order": { "$ref": "#/components/schemas/PaddleOrder", "description": "Record del pagamento di servizio Paddle limitato allo spazio di lavoro." }, "return_url": { "description": "URL del pannello del portafoglio per una ricarica, URL di riconciliazione dei prezzi per un pagamento di servizio. Un URL di ritorno da solo non dimostra mai il pagamento.", "format": "uri", "type": "string" } }, "required": [ "order", "client_token", "approval_url", "return_url" ], "type": "object" }, "PaddleReconcileInput": { "additionalProperties": false, "properties": { "transaction_id": { "description": "ID txn_ originale facoltativo, usato per recuperare una risposta di creazione persa. Il backend verifica indipendentemente l'ordine locale, il tenant, il prodotto, la valuta e l'importo. Non può sostituire una transazione già associata.", "type": "string" } }, "required": [], "type": "object" }, "PaddleSettings": { "additionalProperties": false, "properties": { "api_key_configured": { "description": "Indica se questo canale accetta nuovi checkout. La riconciliazione storica rimane disponibile con le credenziali conservate.", "type": "boolean" }, "checkout_url": { "description": "Usare questa pagina su un dominio approvato come link di pagamento predefinito di Paddle.", "format": "uri", "type": "string" }, "client_token": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "currencies": { "description": "Valute distinte accettate da questo canale; gli importi usano due cifre decimali.", "items": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "type": "array" }, "enabled": { "description": "Indica se questo canale accetta nuovi checkout. La riconciliazione storica rimane disponibile con le credenziali conservate.", "type": "boolean" }, "maximum_cents": { "description": "Ricarica massima del portafoglio in unità monetarie minime; valore predefinito 100000 e non deve essere inferiore a minimum_cents.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "minimum_cents": { "description": "Ricarica minima del portafoglio in unità monetarie minime; valore predefinito 100.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "Ambiente di pagamento. I record sandbox e live sono isolati.", "enum": [ "sandbox", "live" ], "type": "string" }, "product_id": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "version": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "webhook_secret_configured": { "description": "Indica se questo canale accetta nuovi checkout. La riconciliazione storica rimane disponibile con le credenziali conservate.", "type": "boolean" }, "webhook_url": { "description": "Registrare questo URL assoluto come destinazione delle notifiche Paddle.", "format": "uri", "type": "string" } }, "required": [ "enabled", "mode", "client_token", "product_id", "currencies", "api_key_configured", "webhook_secret_configured", "version", "webhook_url", "checkout_url" ], "type": "object" }, "PaddleSettingsInput": { "additionalProperties": false, "properties": { "api_key": { "description": "Cifrata a riposo. Un valore vuoto conserva quello esistente salvo che clear_api_key sia true.", "maxLength": 1000, "type": "string", "writeOnly": true }, "clear_api_key": { "description": "Indica se questo canale accetta nuovi checkout. La riconciliazione storica rimane disponibile con le credenziali conservate.", "type": "boolean" }, "clear_webhook_secret": { "description": "Indica se questo canale accetta nuovi checkout. La riconciliazione storica rimane disponibile con le credenziali conservate.", "type": "boolean" }, "client_token": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "currencies": { "description": "Valute distinte accettate da questo canale; gli importi usano due cifre decimali.", "items": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "type": "array" }, "enabled": { "description": "Indica se questo canale accetta nuovi checkout. La riconciliazione storica rimane disponibile con le credenziali conservate.", "type": "boolean" }, "expected_version": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "maximum_cents": { "description": "Ricarica massima del portafoglio in unità monetarie minime; valore predefinito 100000 e non deve essere inferiore a minimum_cents.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "minimum_cents": { "description": "Ricarica minima del portafoglio in unità monetarie minime; valore predefinito 100.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "Ambiente di pagamento. I record sandbox e live sono isolati.", "enum": [ "sandbox", "live" ], "type": "string" }, "product_id": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "webhook_secret": { "description": "Segreto privato dell'endpoint usato per autenticare l'esatto corpo originale del webhook.", "maxLength": 1000, "type": "string", "writeOnly": true } }, "required": [ "enabled", "mode", "client_token", "product_id", "currencies", "expected_version" ], "type": "object" }, "PaddleWebhookEvent": { "description": "Evento Paddle Billing non modificato, autenticato con Paddle-Signature e riconciliato indipendentemente tramite l'API Paddle.", "type": "object" }, "PasswordSet": { "additionalProperties": false, "properties": { "password_set": { "type": "boolean" } }, "required": [ "password_set" ], "type": "object" }, "PayPalCheck": { "additionalProperties": false, "properties": { "connected": { "type": "boolean" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [], "type": "object" }, "PayPalInput": { "additionalProperties": false, "properties": { "clear_secret": { "type": "boolean" }, "client_id": { "maxLength": 1000, "type": "string" }, "client_secret": { "description": "Un valore vuoto conserva il Secret salvato, salvo clear_secret=true", "maxLength": 1000, "type": "string", "writeOnly": true }, "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "expected_version": { "type": "string" }, "maximum_cents": { "maximum": 100000000, "type": "integer" }, "merchant_id": { "maxLength": 64, "type": "string" }, "minimum_cents": { "minimum": 1, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "webhook_id": { "maxLength": 1000, "type": "string" } }, "required": [ "enabled", "mode", "client_id", "merchant_id", "webhook_id", "currencies", "minimum_cents", "maximum_cents", "expected_version" ], "type": "object" }, "PayPalOrder": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Importo in centesimi; le registrazioni contabili possono essere accrediti positivi o addebiti negativi.", "type": "integer" }, "approval_url": { "description": "URL di approvazione del pagatore PayPal; non è una prova del pagamento.", "format": "uri", "type": "string" }, "capture_id": { "description": "Identificativo dell'acquisizione PayPal.", "type": [ "string", "null" ] }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "credited_at": { "anyOf": [ { "description": "Ora di accredito della ricarica oppure null.", "format": "date-time", "type": "string" }, { "description": "Ora di accredito della ricarica oppure null.", "type": "null" } ], "description": "Ora di accredito della ricarica oppure null." }, "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" }, "paypal_order_id": { "description": "Identificativo dell'ordine PayPal, distinto dall'UUID del record locale.", "type": [ "string", "null" ] }, "purchase_id": { "description": "UUID dell'acquisto di pacchetto correlato.", "type": [ "string", "null" ] }, "refunded_cents": { "description": "Importo rimborsato cumulativo in centesimi.", "type": "integer" }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "type": "string" }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "creating", "created", "credited", "refunded" ], "type": "string" }, "upgrade_id": { "anyOf": [ { "description": "UUID dell'upgrade correlato oppure vuoto.", "format": "uuid", "type": "string" }, { "description": "UUID dell'upgrade correlato oppure vuoto.", "type": "null" } ], "description": "UUID dell'upgrade correlato oppure vuoto." } }, "required": [], "type": "object" }, "PayPalOrderList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/PayPalOrder" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [], "type": "object" }, "PayPalRefund": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Rimborso in denaro richiesto sul metodo originale, in centesimi.", "type": "integer" }, "attempts": { "type": "integer" }, "case_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "format": "uuid", "type": "string" }, "paypal_refund_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "request_id": { "type": "string" }, "reserved": { "description": "True mentre l'importo del portafoglio è bloccato. Un timeout di trasporto mantiene il blocco finché la stessa richiesta non viene riconciliata.", "type": "boolean" }, "status": { "enum": [ "pending", "completed", "failed" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "order_id", "request_id", "mode", "currency", "amount_cents", "reason", "status", "reserved", "attempts", "paypal_refund_id", "created_at", "updated_at" ], "type": "object" }, "PayPalSettings": { "additionalProperties": false, "properties": { "client_id": { "maxLength": 1000, "type": "string" }, "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "maximum_cents": { "maximum": 100000000, "type": "integer" }, "merchant_id": { "maxLength": 64, "type": "string" }, "minimum_cents": { "minimum": 1, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "secret_configured": { "type": "boolean" }, "version": { "type": "string" }, "webhook_id": { "maxLength": 1000, "type": "string" }, "webhook_url": { "format": "uri", "type": "string" } }, "required": [], "type": "object" }, "PaymentChannel": { "additionalProperties": false, "properties": { "currencies": { "description": "Valute distinte accettate da questo canale; gli importi usano due cifre decimali.", "items": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "type": "array" }, "enabled": { "description": "Indica se questo canale accetta nuovi checkout. La riconciliazione storica rimane disponibile con le credenziali conservate.", "type": "boolean" }, "mode": { "description": "Ambiente di pagamento. I record sandbox e live sono isolati.", "enum": [ "sandbox", "live" ], "type": "string" }, "name": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "provider": { "description": "Fornitore di pagamento: PayPal, Paddle o Waffo Pancake.", "enum": [ "paypal", "paddle", "waffo" ], "type": "string" }, "version": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "wallet_topup": { "description": "Indica se questo canale accetta nuovi checkout. La riconciliazione storica rimane disponibile con le credenziali conservate.", "type": "boolean" } }, "required": [ "provider", "name", "enabled", "mode", "currencies", "wallet_topup" ], "type": "object" }, "PaymentChannelInput": { "additionalProperties": false, "properties": { "paddle_enabled": { "description": "Indica se questo canale accetta nuovi checkout. La riconciliazione storica rimane disponibile con le credenziali conservate.", "type": "boolean" }, "paddle_version": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "paypal_enabled": { "description": "Indica se questo canale accetta nuovi checkout. La riconciliazione storica rimane disponibile con le credenziali conservate.", "type": "boolean" }, "paypal_version": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "waffo_enabled": { "description": "Interruttore Waffo facoltativo; i campi omessi ne conservano lo stato corrente.", "type": "boolean" }, "waffo_version": { "description": "Versione della configurazione obbligatoria quando si modifica l'interruttore Waffo.", "type": "string" } }, "required": [ "paypal_enabled", "paddle_enabled", "paypal_version", "paddle_version" ], "type": "object" }, "PaymentChannels": { "additionalProperties": false, "properties": { "items": { "description": "Record visibili a questo amministratore o spazio di lavoro.", "items": { "$ref": "#/components/schemas/PaymentChannel" }, "type": "array" }, "mode": { "description": "Ambiente di pagamento. I record sandbox e live sono isolati.", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "items", "mode" ], "type": "object" }, "PendingPlan": { "additionalProperties": false, "properties": { "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "type": "string" }, "effective_month": { "description": "Mese UTC YYYY-MM in cui la pianificazione diventa effettiva.", "type": "string" }, "plan": { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "type": "string" }, "price_version": { "description": "Revisione del prezzo congelata; un input obsoleto può causare PLAN_VERSION_CONFLICT.", "type": "string" } }, "required": [], "type": "object" }, "Period": { "additionalProperties": false, "properties": { "base_covered": { "description": "Indica se un pacchetto acquistato copre già l'addebito di base.", "type": "boolean" }, "base_micros": { "description": "Addebito di base in milionesimi dell'unità valutaria.", "type": "integer" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "hard_limit": { "description": "Indica se i nuovi dispositivi fatturabili vengono rifiutati al raggiungimento della quota.", "type": "boolean" }, "included_devices": { "description": "Quota inclusa di dispositivi attivi.", "type": "integer" }, "month": { "description": "Mese UTC YYYY-MM; i valori di query omessi usano il mese corrente. Le attività di fatturazione richiedono un mese concluso.", "type": "string" }, "payment_mode": { "description": "Ambiente di pagamento, sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "type": "string" }, "plan_name": { "description": "Nome visualizzato del piano.", "type": "string" }, "price_version": { "description": "Revisione del prezzo congelata; un input obsoleto può causare PLAN_VERSION_CONFLICT.", "type": "string" }, "unit_micros": { "description": "Prezzo per dispositivo attivo eccedente, in milionesimi.", "type": "integer" } }, "required": [ "month", "plan", "currency", "price_version" ], "type": "object" }, "PlanChange": { "additionalProperties": false, "properties": { "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "plan": { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "price_version": { "description": "Revisione del prezzo congelata; un input obsoleto può causare PLAN_VERSION_CONFLICT.", "type": "string" } }, "required": [ "plan", "currency" ], "type": "object" }, "PlanGift": { "additionalProperties": false, "properties": { "batch_id": { "format": "uuid", "type": "string" }, "cancel_reason": { "type": "string" }, "cancelled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "cancelled_by": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "granted", "cancelled" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "value_cents": { "type": "integer" } }, "required": [ "id", "batch_id", "tenant_id", "user_id", "purchase_id", "value_cents", "status", "starts_at", "ends_at", "created_at", "cancelled_at" ], "type": "object" }, "PlanGiftBatch": { "additionalProperties": false, "properties": { "actor_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "price_version": { "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "type": "string" }, "start_mode": { "type": "string" }, "tenant_count": { "type": "integer" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_count": { "type": "integer" } }, "required": [ "id", "actor_id", "request_id", "plan", "plan_name", "currency", "price_version", "term_months", "mode", "start_mode", "reason", "user_count", "tenant_count", "created_at" ], "type": "object" }, "PlanGiftCancellation": { "additionalProperties": false, "properties": { "cancelled": { "type": "boolean" } }, "required": [ "cancelled" ], "type": "object" }, "PlanGiftInput": { "additionalProperties": false, "properties": { "currency": { "maxLength": 3, "minLength": 3, "type": "string" }, "fingerprint": { "maxLength": 64, "minLength": 64, "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "price_version": { "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "start_mode": { "default": "after_current", "enum": [ "after_current", "immediate" ], "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "user_ids", "term_months", "mode", "start_mode", "reason", "request_id", "fingerprint" ], "type": "object" }, "PlanGiftList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PlanGiftRow" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PlanGiftPreview": { "additionalProperties": false, "properties": { "fingerprint": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/PlanGiftTarget" }, "type": "array" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan_name": { "type": "string" }, "start_mode": { "default": "after_current", "enum": [ "after_current", "immediate" ], "type": "string" }, "tenant_count": { "type": "integer" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_count": { "type": "integer" }, "value_cents": { "type": "integer" } }, "required": [ "fingerprint", "plan_name", "value_cents", "user_count", "tenant_count", "mode", "term_months", "start_mode", "items" ], "type": "object" }, "PlanGiftPreviewInput": { "additionalProperties": false, "properties": { "currency": { "maxLength": 3, "minLength": 3, "type": "string" }, "fingerprint": { "maxLength": 64, "minLength": 64, "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "price_version": { "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "start_mode": { "default": "after_current", "enum": [ "after_current", "immediate" ], "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "user_ids", "mode", "reason" ], "type": "object" }, "PlanGiftResult": { "additionalProperties": false, "properties": { "batch": { "$ref": "#/components/schemas/PlanGiftBatch" }, "items": { "items": { "$ref": "#/components/schemas/PlanGift" }, "type": "array" } }, "required": [ "batch", "items" ], "type": "object" }, "PlanGiftRow": { "additionalProperties": false, "properties": { "actor_email": { "type": "string" }, "batch_id": { "format": "uuid", "type": "string" }, "cancel_reason": { "type": "string" }, "cancelled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "cancelled_by": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "email": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "granted", "cancelled" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_id": { "format": "uuid", "type": "string" }, "value_cents": { "type": "integer" } }, "required": [ "id", "batch_id", "tenant_id", "user_id", "purchase_id", "value_cents", "status", "starts_at", "ends_at", "created_at", "cancelled_at" ], "type": "object" }, "PlanGiftTarget": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "email": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "previous_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "price_version": { "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "value_cents": { "type": "integer" } }, "required": [ "user_id", "email", "tenant_id", "tenant_name", "starts_at", "ends_at", "previous_end", "plan", "plan_name", "currency", "price_version", "value_cents" ], "type": "object" }, "PlanInput": { "additionalProperties": false, "properties": { "api_hard_limit": { "type": "boolean" }, "api_unit_amount": { "description": "Numero decimale non negativo per chiamata API riuscita, massimo sei cifre decimali", "type": "string" }, "base_amount": { "description": "Numero decimale non negativo; massimo due cifre decimali", "type": "string" }, "currency": { "description": "Deve essere configurato; le offerte del catalogo EUR sono disabilitate", "pattern": "^[A-Z]{3}$", "type": "string" }, "description": { "maxLength": 1000, "type": "string" }, "enabled": { "type": "boolean" }, "expected_version": { "description": "Versione corrente; vuota alla creazione", "type": "string" }, "hard_limit": { "type": "boolean" }, "included_api_calls": { "description": "null = illimitato; 0 = nessuna chiamata riuscita inclusa", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "maximum": 1000000000, "minimum": 0, "type": "integer" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "public": { "type": "boolean" }, "renewal_only": { "description": "I clienti esistenti con pacchetti pagati o regalati possono rinnovare in anticipo o dopo la scadenza nello stesso ambiente e nella stessa valuta. Nascosto dai nuovi acquisti pubblici.", "type": "boolean" }, "sort_order": { "maximum": 10000, "minimum": 0, "type": "integer" }, "terms": { "description": "Esattamente una voce per 1, 3, 6 e 12 mesi, ciascuna con disponibilità e prezzo totale propri.", "items": { "$ref": "#/components/schemas/PlanTermInput" }, "maxItems": 4, "minItems": 4, "type": "array" }, "unit_amount": { "description": "Numero decimale non negativo; massimo sei cifre decimali", "type": "string" } }, "required": [ "plan", "currency", "name", "base_amount", "unit_amount" ], "type": "object" }, "PlanList": { "additionalProperties": false, "properties": { "billing_unit": { "type": "string" }, "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "default_plan": { "anyOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "null" } ] }, "items": { "items": { "$ref": "#/components/schemas/Price" }, "type": "array" }, "maximum_cents": { "type": "integer" }, "minimum_cents": { "type": "integer" }, "payment_channels": { "description": "Configurazione dei canali di pagamento disponibili. Mostrare soltanto i canali abilitati che corrispondono all'ambiente di fatturazione attivo e alla valuta dell'acquisto.", "items": { "$ref": "#/components/schemas/PaymentChannel" }, "type": "array" }, "paypal_enabled": { "type": "boolean" }, "sandbox": { "type": "boolean" }, "timezone": { "type": "string" } }, "required": [], "type": "object" }, "PlanPurchase": { "additionalProperties": false, "properties": { "api_calls": { "description": "Per PurchaseList.active: chiamate riuscite nel mese della quota corrente. Le voci storiche contengono i totali sull'intera durata.", "type": "integer" }, "api_hard_limit": { "description": "Indica se le chiamate di esecuzione si interrompono al raggiungimento della quota API.", "type": "boolean" }, "api_overage_cents": { "description": "Mese della quota corrente nella vista attiva; addebiti degli sforamenti API sull'intera durata nelle voci storiche.", "type": "integer" }, "api_unit_micros": { "description": "Prezzo per chiamata di esecuzione eccedente, in milionesimi.", "minimum": 0, "type": "integer" }, "base_cents": { "description": "Addebito iniziale effettivo per l'intero contratto; zero per un regalo. La vista attiva dell'upgrade effettivo contiene il prezzo completo del piano di destinazione per la durata corrispondente.", "type": "integer" }, "cancelled_at": { "anyOf": [ { "description": "Timestamp di annullamento del contratto oppure null.", "format": "date-time", "type": "string" }, { "description": "Timestamp di annullamento del contratto oppure null.", "type": "null" } ], "description": "Timestamp di annullamento del contratto oppure null." }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "current_cycle_index": { "description": "Indice del ciclo della quota corrente.", "maximum": 11, "minimum": 0, "type": "integer" }, "current_upgrade_id": { "description": "Vuoto prima di un upgrade. Altrimenti indica l'ultimo PlanUpgrade applicato. La risposta attiva include l'istantanea del suo piano effettivo, mentre gli acquisti storici conservano il prezzo di vendita originale.", "type": "string" }, "cycle_ends_at": { "description": "Fine del ciclo della quota corrente, UTC.", "format": "date-time", "type": "string" }, "cycle_starts_at": { "description": "Inizio del ciclo della quota corrente, UTC.", "format": "date-time", "type": "string" }, "effective_included_devices": { "description": "Quota dei dispositivi dopo l'upgrade applicato. Le istantanee originali degli acquisti rimangono invariate.", "minimum": 0, "type": "integer" }, "effective_plan": { "description": "Diritto corrente dopo un livello aggiuntivo di upgrade esplicito. L'elenco acquisti conserva plan/base_cents originali per la cronologia dei pagamenti; usare questo campo per mostrare il livello attualmente effettivo.", "type": "string" }, "effective_plan_name": { "description": "Diritto corrente dopo un livello aggiuntivo di upgrade esplicito. L'elenco acquisti conserva plan/base_cents originali per la cronologia dei pagamenti; usare questo campo per mostrare il livello attualmente effettivo.", "type": "string" }, "ends_at": { "anyOf": [ { "description": "Timestamp di fine del pacchetto o del ciclo, UTC; può essere null prima dell'attivazione.", "format": "date-time", "type": "string" }, { "description": "Timestamp di fine del pacchetto o del ciclo, UTC; può essere null prima dell'attivazione.", "type": "null" } ], "description": "Timestamp di fine del pacchetto o del ciclo, UTC; può essere null prima dell'attivazione." }, "entitlement_cents": { "description": "Valore del beneficio del pacchetto effettivo corrente per il credito di upgrade, in centesimi della valuta. Un piano da 99 USD regalato ha un beneficio di 9900 centesimi anche se il pagamento originale base_cents è zero. Questo valore non è denaro rimborsabile. Compilato nelle viste dei pacchetti attivi.", "minimum": 0, "type": "integer" }, "gift_batch_id": { "description": "Identificativo del batch di regali; vuoto per gli acquisti ordinari.", "type": "string" }, "gift_follows_current": { "default": false, "description": "Indica un regalo emesso dal livello corrente del cliente. Il regalo conserva il valore originale del diritto e un pagamento in denaro pari a zero. Gli upgrade espliciti dell'intera copertura applicano livelli aggiuntivi di diritti separati a ogni regalo non scaduto e conservano il record del regalo originale con pagamento zero.", "type": "boolean" }, "hard_limit": { "description": "Indica se i nuovi dispositivi fatturabili vengono rifiutati al raggiungimento della quota.", "type": "boolean" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "included_api_calls": { "description": "null = illimitato; 0 = nessuna chiamata riuscita inclusa", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "description": "Quota inclusa di dispositivi attivi.", "type": "integer" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" }, "overage_cents": { "description": "Mese della quota corrente nella vista attiva; addebiti degli sforamenti dei dispositivi sull'intera durata nelle voci storiche.", "type": "integer" }, "plan": { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "plan_name": { "description": "Nome visualizzato del piano.", "type": "string" }, "price_version": { "description": "Revisione del prezzo congelata; un input obsoleto può causare PLAN_VERSION_CONFLICT.", "type": "string" }, "refunded_cents": { "description": "Importo rimborsato cumulativo in centesimi.", "type": "integer" }, "renewal": { "description": "Indica se si tratta di un contratto di rinnovo.", "type": "boolean" }, "renewal_of": { "description": "ID del pacchetto precedente pagato o regalato. Conserva la catena dei rinnovi e la cronologia originale degli acquisti.", "type": "string" }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "type": "string" }, "service_credit_basis_cents": { "description": "Importo di base in centesimi per il calcolo dei crediti di servizio.", "type": "integer" }, "service_credit_basis_seconds": { "description": "Base temporale in secondi per il calcolo dei crediti di servizio.", "type": "integer" }, "source": { "description": "Origine del diritto, ad esempio purchase o gift.", "enum": [ "purchase", "gift", "auto_renewal" ], "type": "string" }, "starts_at": { "anyOf": [ { "description": "Timestamp di inizio del pacchetto o del ciclo, UTC.", "format": "date-time", "type": "string" }, { "description": "Timestamp di inizio del pacchetto o del ciclo, UTC.", "type": "null" } ], "description": "Timestamp di inizio del pacchetto o del ciclo, UTC." }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "pending", "active", "cancelled", "expired" ], "type": "string" }, "term_months": { "default": 1, "description": "Numero di mesi della durata acquistata.", "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "total_api_calls": { "description": "Chiamate di esecuzione cumulative nell'intero contratto.", "type": "integer" }, "total_api_overage_cents": { "description": "Sforamenti API cumulativi del contratto, in centesimi.", "type": "integer" }, "total_device_overage_cents": { "description": "Sforamenti cumulativi dei dispositivi del contratto, in centesimi.", "type": "integer" }, "unit_micros": { "description": "Prezzo per dispositivo attivo eccedente, in milionesimi.", "type": "integer" } }, "required": [], "type": "object" }, "PlanTermInput": { "additionalProperties": false, "properties": { "amount": { "description": "Totale non negativo per la durata; al massimo due cifre decimali. L'importo per un mese deve essere uguale a base_amount.", "type": "string" }, "enabled": { "type": "boolean" }, "months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" } }, "required": [ "months", "enabled", "amount" ], "type": "object" }, "PlanTermPrice": { "additionalProperties": false, "properties": { "base_cents": { "description": "Addebito totale per la durata selezionata, in centesimi della valuta. Le quote mensili non vengono moltiplicate per questa durata.", "minimum": 0, "type": "integer" }, "enabled": { "description": "Indica se l'endpoint webhook è abilitato.", "type": "boolean" }, "months": { "default": 1, "description": "Numero di mesi della durata di acquisto.", "enum": [ 1, 3, 6, 12 ], "type": "integer" } }, "required": [ "months", "enabled", "base_cents" ], "type": "object" }, "PlanUpgrade": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Pagamento complessivo per tutte le voci in parts. Addebitato una sola volta in modo atomico. Gli altri campi pro rata dell'elemento principale descrivono soltanto il periodo corrente; esaminare parts per il valore originale, il valore di destinazione, i secondi rimanenti e la differenza individuale di ogni periodo.", "type": "integer" }, "api_hard_limit": { "description": "Indica se le chiamate di esecuzione si interrompono al raggiungimento della quota API.", "type": "boolean" }, "api_unit_micros": { "description": "Nuova tariffa di sforamento API in milionesimi della valuta.", "type": "integer" }, "applied_at": { "anyOf": [ { "description": "Ora in cui l'upgrade è diventato effettivo oppure null.", "format": "date-time", "type": "string" }, { "description": "Ora in cui l'upgrade è diventato effettivo oppure null.", "type": "null" } ], "description": "Ora in cui l'upgrade è diventato effettivo oppure null." }, "base_cents": { "description": "Prezzo mensile di destinazione in centesimi, non l'importo dovuto ora.", "type": "integer" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "currency": { "description": "Stessa valuta del pacchetto corrente.", "type": "string" }, "cycle_seconds": { "description": "Durata del ciclo acquistato originale in secondi.", "type": "integer" }, "ends_at": { "description": "Timestamp di fine del pacchetto o del ciclo, UTC; può essere null prima dell'attivazione.", "format": "date-time", "type": "string" }, "expires_at": { "description": "15 minuti dopo la creazione o alla scadenza del piano originale, a seconda di quale avvenga prima.", "format": "date-time", "type": "string" }, "hard_limit": { "description": "Indica se i nuovi dispositivi fatturabili vengono rifiutati al raggiungimento della quota.", "type": "boolean" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "included_api_calls": { "anyOf": [ { "description": "Quota API totale per il ciclo esistente. Null indica illimitata. Le chiamate precedenti continuano a essere conteggiate.", "type": "integer" }, { "description": "Chiamate di esecuzione riuscite incluse; null indica illimitate e 0 indica nessuna inclusa.", "type": "null" } ], "description": "Chiamate di esecuzione riuscite incluse; null indica illimitate e 0 indica nessuna inclusa." }, "included_devices": { "description": "Quota totale per il ciclo esistente; l'utilizzo precedente dei dispositivi continua a essere conteggiato.", "type": "integer" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" }, "parent_id": { "description": "I livelli aggiuntivi di diritti applicati internamente fanno riferimento al singolo addebito principale. Questi record subordinati sono esclusi dalla cronologia degli upgrade del cliente e dai conteggi delle vendite.", "format": "uuid", "type": "string" }, "parts": { "description": "Tutti i periodi correnti e futuri pagati/regalati non scaduti, in ordine di data. Upgrade obbligatorio dell'intera copertura; nessun sottoinsieme di periodi selezionabile.", "items": { "$ref": "#/components/schemas/UpgradePart" }, "type": "array" }, "plan": { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "type": "string" }, "plan_name": { "description": "Nome visualizzato del piano.", "type": "string" }, "previous_base_cents": { "description": "Prezzo mensile corrente effettivo in centesimi.", "type": "integer" }, "previous_plan_name": { "description": "Nome visualizzato del piano prima dell'upgrade.", "type": "string" }, "previous_upgrade_id": { "description": "ID dell'upgrade precedente oppure vuoto per il primo upgrade. Usato per rifiutare preventivi obsoleti.", "type": "string" }, "price_version": { "description": "Versione del prezzo di destinazione congelata.", "type": "string" }, "purchase_id": { "description": "UUID dell'acquisto di pacchetto correlato.", "format": "uuid", "type": "string" }, "remaining_seconds": { "description": "Secondi rimanenti alla creazione del preventivo, arrotondati per eccesso.", "type": "integer" }, "request_id": { "description": "Chiave stabile generata dal client. Riutilizzarla con parametri di preventivo diversi restituisce 409.", "type": "string" }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "pending", "applied", "expired" ], "type": "string" }, "unit_micros": { "description": "Nuova tariffa di sforamento per dispositivo in milionesimi della valuta.", "type": "integer" } }, "required": [ "id", "request_id", "mode", "purchase_id", "previous_upgrade_id", "plan", "plan_name", "previous_plan_name", "currency", "price_version", "previous_base_cents", "base_cents", "amount_cents", "included_devices", "unit_micros", "hard_limit", "included_api_calls", "api_unit_micros", "api_hard_limit", "remaining_seconds", "cycle_seconds", "ends_at", "expires_at", "status", "created_at", "applied_at" ], "type": "object" }, "PlatformOperation": { "additionalProperties": false, "properties": { "action": { "type": "string" }, "actor_email": { "type": "string" }, "actor_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "details": { "description": "Stringa JSON contenente soltanto modifiche amministrative esplicite; mai password, token o credenziali di pagamento.", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "type": "string" }, "resource_id": { "type": "string" }, "tenant_id": { "type": "string" }, "user_email": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "id", "actor_id", "action", "user_id", "tenant_id", "resource_id", "reason", "details", "request_id", "created_at", "actor_email", "user_email" ], "type": "object" }, "PlatformOperationList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PlatformOperation" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PlatformOverview": { "additionalProperties": false, "properties": { "at": { "format": "date-time", "type": "string" }, "counts": { "additionalProperties": false, "properties": { "active_packages": { "type": "integer" }, "active_workspaces": { "type": "integer" }, "disabled_users": { "type": "integer" }, "enabled_plans": { "type": "integer" }, "expiring_packages": { "type": "integer" }, "failed_mail": { "type": "integer" }, "gift_packages": { "type": "integer" }, "new_users": { "type": "integer" }, "suspended_workspaces": { "type": "integer" }, "users": { "type": "integer" }, "verified_users": { "type": "integer" } }, "required": [ "users", "verified_users", "disabled_users", "new_users", "active_workspaces", "suspended_workspaces", "active_packages", "expiring_packages", "gift_packages", "failed_mail", "enabled_plans" ], "type": "object" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "paypal_enabled": { "type": "boolean" } }, "required": [ "counts", "mode", "paypal_enabled", "at" ], "type": "object" }, "PlatformReason": { "additionalProperties": false, "properties": { "reason": { "maxLength": 500, "minLength": 1, "type": "string" } }, "required": [ "reason" ], "type": "object" }, "PlatformRevocation": { "additionalProperties": false, "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "type": "object" }, "PlatformUser": { "additionalProperties": false, "properties": { "admin_note": { "description": "Nota privata della piattaforma. I campi del profilo del cliente rimangono invariati.", "maxLength": 2000, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "email": { "format": "email", "type": "string" }, "email_verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "is_platform_admin": { "type": "boolean" }, "last_login_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "note_version": { "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" }, "tenant_status": { "enum": [ "active", "suspended" ], "type": "string" }, "tenant_updated_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "tenant_id", "tenant_name", "tenant_status", "tenant_updated_at", "email", "name", "role", "status", "is_platform_admin", "email_verified_at", "created_at", "updated_at", "last_login_at", "admin_note", "note_version" ], "type": "object" }, "PlatformUserDetail": { "additionalProperties": false, "properties": { "counts": { "additionalProperties": false, "properties": { "licenses": { "type": "integer" }, "products": { "type": "integer" }, "users": { "type": "integer" } }, "required": [ "users", "products", "licenses" ], "type": "object" }, "payments": { "items": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "paid_cents": { "type": "integer" }, "refunded_cents": { "type": "integer" } }, "required": [ "mode", "currency", "paid_cents", "refunded_cents" ], "type": "object" }, "type": "array" }, "purchases": { "items": { "$ref": "#/components/schemas/PlanPurchase" }, "type": "array" }, "user": { "$ref": "#/components/schemas/PlatformUser" }, "wallets": { "items": { "$ref": "#/components/schemas/Wallet" }, "type": "array" } }, "required": [ "user", "counts", "wallets", "purchases", "payments" ], "type": "object" }, "PlatformUserList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PlatformUser" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PlatformUserUpdate": { "additionalProperties": false, "anyOf": [ { "required": [ "status", "expected_updated_at" ] }, { "required": [ "admin_note", "expected_note_version" ] } ], "properties": { "admin_note": { "maxLength": 2000, "type": "string" }, "expected_note_version": { "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" } }, "required": [ "reason" ], "type": "object" }, "PlatformWorkspaceStatus": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "status": { "enum": [ "active", "suspended" ], "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "PlatformWorkspaceUpdate": { "additionalProperties": false, "properties": { "expected_updated_at": { "format": "date-time", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "status": { "enum": [ "active", "suspended" ], "type": "string" } }, "required": [ "status", "reason", "expected_updated_at" ], "type": "object" }, "Policy": { "additionalProperties": false, "example": { "created_at": "2026-10-18T00:00:00Z", "features": [ "export" ], "heartbeat_seconds": 600, "id": "22222222-2222-4222-8222-222222222222", "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z", "version": 1 }, "properties": { "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "features": { "description": "Fino a 32 identificatori distinti di funzionalità, ciascuno composto da 1–64 caratteri tra lettere ASCII, cifre, punti, trattini o trattini bassi.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita." }, { "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Intervallo di heartbeat online, in secondi. 0 disabilita gli heartbeat periodici. La durata offline consentita si configura separatamente.", "type": "integer" }, "id": { "description": "UUID della politica, usato come policy_id durante l'emissione di una licenza.", "format": "uuid", "type": "string" }, "max_devices": { "description": "Numero massimo di dispositivi simultanei o posti flottanti per licenza.", "type": "integer" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "Nome leggibile dall'utente; consultare i vincoli di lunghezza.", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited: uso offline a tempo limitato; none: nessun uso offline; permanent: nessun limite temporale offline aggiuntivo, ma la scadenza della licenza continua ad applicarsi.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Secondi offline consentiti: 1–31536000 per limited, 0 per none/permanent. Non è l'intervallo di heartbeat. Con gli heartbeat attivi, le nuove politiche offline limitate devono rispettare offline_seconds \u003e= 3 × heartbeat_seconds; anche i lease delle licenze flottanti devono coprire almeno tre intervalli di heartbeat.", "maximum": 31536000, "minimum": 0, "type": "integer" }, "product_id": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" }, "updated_at": { "description": "Timestamp dell'ultimo aggiornamento in UTC.", "format": "date-time", "type": "string" }, "version": { "description": "La revisione della policy aumenta a ogni modifica. Quando si applica a licenze esistenti, verifica che l'anteprima sia ancora attuale.", "type": "integer" } }, "required": [ "id", "product_id", "mode", "version" ], "type": "object" }, "PolicyCapabilities": { "additionalProperties": false, "properties": { "allow_vm": { "description": "Indica se sono consentite macchine virtuali.", "type": "boolean" }, "device_match": { "description": "Corrispondenza dell'identità system o dell'identità hardware.", "enum": [ "system", "hardware" ], "type": "string" }, "license_model": { "description": "Associazione del dispositivo node_locked o posti flottanti.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "Giorni di manutenzione dalla prima attivazione; 0 indica nessuna scadenza della manutenzione.", "maximum": 36500, "minimum": 0, "type": "integer" }, "max_version": { "description": "Versione massima consentita dell'applicazione; vuoto indica nessun limite superiore.", "type": "string" }, "meter_rules": { "description": "Regole di misurazione delle funzionalità; vuoto indica che non ne è configurata alcuna.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Indica se sono consentiti utilizzi eccedenti della funzionalità.", "type": "boolean" }, "feature": { "description": "Identificativo di una funzionalità a consumo, che deve esistere nelle funzionalità della politica.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Utilizzi della funzionalità inclusi per periodo di misurazione (non un limite di paginazione).", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Utilizzo eccedente massimo consentito; disabilitato quando allow_overage è false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Istantanea di fatturazione mensile UTC predefinita; le regole di misurazione usano month/day/lifetime e le righe di utilizzo usano la chiave concreta del periodo.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "Versione minima consentita dell'applicazione; vuoto indica nessun limite inferiore.", "type": "string" }, "policy_id": { "description": "UUID della politica; deve appartenere al prodotto al momento dell'emissione.", "format": "uuid", "type": "string" }, "policy_version": { "description": "Revisione della politica; inviare il valore corrente quando si modificano tutte le funzionalità per impedire scritture obsolete.", "type": "integer" }, "product_id": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" }, "require_hardware": { "description": "Indica se è richiesta un'identità hardware utilizzabile.", "type": "boolean" }, "self_release_limit": { "description": "Rilasci autonomi consentiti in una finestra mobile di 30 giorni, 0–100; 0 li disabilita.", "maximum": 100, "minimum": 0, "type": "integer" }, "session_seconds": { "description": "Durata del lease di un posto flottante senza heartbeat, in secondi, 20–86400; deve rispettare i vincoli di esecuzione della politica.", "maximum": 86400, "minimum": 20, "type": "integer" }, "updated_at": { "description": "Timestamp dell'ultimo aggiornamento in UTC.", "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "PolicyCapabilitiesInput": { "additionalProperties": false, "description": "Definisce la modalità di emissione, i limiti di dispositivi/posti, le funzionalità e le regole di esecuzione. Una politica non memorizza alcuna durata di validità. policy_version è obbligatorio per impedire modifiche obsolete.", "properties": { "allow_vm": { "description": "Indica se sono consentite macchine virtuali.", "type": "boolean" }, "device_match": { "description": "Corrispondenza dell'identità system o dell'identità hardware.", "enum": [ "system", "hardware" ], "type": "string" }, "features": { "description": "Fino a 32 identificatori distinti di funzionalità, ciascuno composto da 1–64 caratteri tra lettere ASCII, cifre, punti, trattini o trattini bassi.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita." }, { "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "0 disabilita esplicitamente gli heartbeat periodici; altrimenti 600–86400 secondi (minimo 10 minuti). Indipendente dalla durata offline consentita.", "type": "integer" }, "license_model": { "description": "Associazione del dispositivo node_locked o posti flottanti.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "Giorni di manutenzione dalla prima attivazione; 0 indica nessuna scadenza della manutenzione.", "maximum": 36500, "minimum": 0, "type": "integer" }, "max_devices": { "description": "Numero massimo di dispositivi simultanei o posti flottanti per licenza.", "maximum": 10000, "minimum": 1, "type": "integer" }, "max_version": { "description": "Versione massima consentita dell'applicazione; vuoto indica nessun limite superiore.", "type": "string" }, "meter_rules": { "description": "Regole di misurazione delle funzionalità; vuoto indica che non ne è configurata alcuna.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Indica se sono consentiti utilizzi eccedenti della funzionalità.", "type": "boolean" }, "feature": { "description": "Identificativo di una funzionalità a consumo, che deve esistere nelle funzionalità della politica.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Utilizzi della funzionalità inclusi per periodo di misurazione (non un limite di paginazione).", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Utilizzo eccedente massimo consentito; disabilitato quando allow_overage è false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Istantanea di fatturazione mensile UTC predefinita; le regole di misurazione usano month/day/lifetime e le righe di utilizzo usano la chiave concreta del periodo.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "Versione minima consentita dell'applicazione; vuoto indica nessun limite inferiore.", "type": "string" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "Nome leggibile dall'utente; consultare i vincoli di lunghezza.", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "Durata offline consentita limited, none o permanent; la scadenza della licenza continua ad applicarsi.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Limited: 1–31536000 secondi e almeno 3 × heartbeat_seconds con gli heartbeat attivi; none/permanent: 0", "maximum": 31536000, "minimum": 0, "type": "integer" }, "policy_version": { "description": "Revisione della politica; inviare il valore corrente quando si modificano tutte le funzionalità per impedire scritture obsolete.", "minimum": 1, "type": "integer" }, "require_hardware": { "description": "Indica se è richiesta un'identità hardware utilizzabile.", "type": "boolean" }, "self_release_limit": { "description": "Rilasci autonomi consentiti in una finestra mobile di 30 giorni, 0–100; 0 li disabilita.", "maximum": 100, "minimum": 0, "type": "integer" }, "session_seconds": { "description": "Durata del lease di un posto flottante senza heartbeat, in secondi, 20–86400; deve rispettare i vincoli di esecuzione della politica.", "maximum": 86400, "minimum": 20, "type": "integer" } }, "required": [ "policy_version" ], "type": "object" }, "PolicyCreate": { "additionalProperties": false, "description": "Definisce la modalità di emissione, i limiti di dispositivi/posti, le funzionalità e le regole di esecuzione. Una politica non memorizza alcuna durata di validità.", "properties": { "allow_vm": { "description": "Indica se sono consentite macchine virtuali.", "type": "boolean" }, "device_match": { "description": "Corrispondenza dell'identità system o dell'identità hardware.", "enum": [ "system", "hardware" ], "type": "string" }, "features": { "description": "Identificatori delle funzionalità consentite, ad esempio [\"export\"]. Devono corrispondere agli argomenti CheckFeature dell'applicazione.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita." }, { "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Intervallo di heartbeat online, in secondi. 0 disabilita gli heartbeat periodici. La durata offline consentita si configura separatamente.", "type": "integer" }, "license_model": { "description": "Associazione del dispositivo node_locked o posti flottanti.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "Giorni di manutenzione dalla prima attivazione; 0 indica nessuna scadenza della manutenzione.", "maximum": 36500, "minimum": 0, "type": "integer" }, "max_devices": { "description": "Limite di dispositivi per licenza, 1–10000; in modalità floating indica il limite dei posti simultanei.", "maximum": 10000, "minimum": 1, "type": "integer" }, "max_version": { "description": "Versione massima consentita dell'applicazione; vuoto indica nessun limite superiore.", "type": "string" }, "meter_rules": { "description": "Regole di misurazione delle funzionalità; vuoto indica che non ne è configurata alcuna.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Indica se sono consentiti utilizzi eccedenti della funzionalità.", "type": "boolean" }, "feature": { "description": "Identificativo di una funzionalità a consumo, che deve esistere nelle funzionalità della politica.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Utilizzi della funzionalità inclusi per periodo di misurazione (non un limite di paginazione).", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Utilizzo eccedente massimo consentito; disabilitato quando allow_overage è false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Istantanea di fatturazione mensile UTC predefinita; le regole di misurazione usano month/day/lifetime e le righe di utilizzo usano la chiave concreta del periodo.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "Versione minima consentita dell'applicazione; vuoto indica nessun limite inferiore.", "type": "string" }, "mode": { "description": "Tipo di licenza: perpetual, timed o trial. Non è un tipo di abbonamento a un piano di fatturazione.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "Nome della politica, ad esempio Pro da 30 giorni.", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited: uso offline a tempo limitato; none: nessun uso offline; permanent: nessun limite temporale offline aggiuntivo, ma la scadenza della licenza continua ad applicarsi.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Secondi offline consentiti: 1–31536000 per limited, 0 per none/permanent. Non è l'intervallo di heartbeat. Con gli heartbeat attivi, le nuove politiche offline limitate devono rispettare offline_seconds \u003e= 3 × heartbeat_seconds; anche i lease delle licenze flottanti devono coprire almeno tre intervalli di heartbeat.", "maximum": 31536000, "minimum": 0, "type": "integer" }, "product_id": { "description": "ID prodotto (UUID).", "format": "uuid", "type": "string" }, "require_hardware": { "description": "Indica se è richiesta un'identità hardware utilizzabile.", "type": "boolean" }, "self_release_limit": { "description": "Rilasci autonomi consentiti in una finestra mobile di 30 giorni, 0–100; 0 li disabilita.", "maximum": 100, "minimum": 0, "type": "integer" }, "session_seconds": { "description": "Durata del lease di un posto flottante senza heartbeat, in secondi, 20–86400; deve rispettare i vincoli di esecuzione della politica.", "maximum": 86400, "minimum": 20, "type": "integer" } }, "required": [ "product_id", "name", "mode", "max_devices" ], "type": "object" }, "PolicyList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/Policy" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "PolicyPreview": { "additionalProperties": false, "properties": { "changes": { "description": "Confronto prima/dopo e motivo del blocco per ogni licenza.", "items": { "additionalProperties": false, "properties": { "active": { "description": "Indicatore della chiave di firma corrente; in un'anteprima della politica, numero di dispositivi/sessioni attivi.", "type": "integer" }, "after": { "additionalProperties": false, "description": "Diritti dopo l'applicazione della politica di destinazione; la durata rimane invariata.", "properties": { "duration_days": { "description": "Giorni specifici della licenza dalla prima attivazione. Obbligatori 1–36500 per l'emissione timed/trial; assenti/null per perpetual. Non vengono mai memorizzati nella politica.", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "type": "null" } ], "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale." }, "features": { "description": "Fino a 32 identificatori distinti di funzionalità, ciascuno composto da 1–64 caratteri tra lettere ASCII, cifre, punti, trattini o trattini bassi.", "items": { "type": "string" }, "type": "array" }, "license_model": { "description": "Associazione del dispositivo node_locked o posti flottanti.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_until": { "anyOf": [ { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, { "description": "Termine della manutenzione per le nuove release; può essere null prima dell'attivazione o quando illimitata.", "type": "null" } ], "description": "Termine della manutenzione per le nuove release; può essere null prima dell'attivazione o quando illimitata." }, "max_devices": { "description": "Numero massimo di dispositivi simultanei o posti flottanti per licenza.", "type": "integer" }, "max_version": { "description": "Versione massima consentita dell'applicazione; vuoto indica nessun limite superiore.", "type": "string" }, "meter_rules": { "description": "Regole di misurazione delle funzionalità; vuoto indica che non ne è configurata alcuna.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Indica se sono consentiti utilizzi eccedenti della funzionalità.", "type": "boolean" }, "feature": { "description": "Identificativo di una funzionalità a consumo, che deve esistere nelle funzionalità della politica.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Utilizzo eccedente massimo consentito; disabilitato quando allow_overage è false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Istantanea di fatturazione mensile UTC predefinita; le regole di misurazione usano month/day/lifetime e le righe di utilizzo usano la chiave concreta del periodo.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "Versione minima consentita dell'applicazione; vuoto indica nessun limite inferiore.", "type": "string" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" } }, "required": [ "mode", "max_devices", "features", "expires_at", "duration_days", "license_model", "meter_rules", "maintenance_until", "min_version", "max_version" ], "type": "object" }, "before": { "additionalProperties": false, "description": "Diritti attualmente emessi e durata della licenza.", "properties": { "capabilities": { "$ref": "#/components/schemas/LicenseCapabilities", "description": "Istantanea delle funzionalità della licenza." }, "duration_days": { "description": "Giorni specifici della licenza dalla prima attivazione. Obbligatori 1–36500 per l'emissione timed/trial; assenti/null per perpetual. Non vengono mai memorizzati nella politica.", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "type": "null" } ], "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale." }, "features": { "description": "Fino a 32 identificatori distinti di funzionalità, ciascuno composto da 1–64 caratteri tra lettere ASCII, cifre, punti, trattini o trattini bassi.", "items": { "type": "string" }, "type": "array" }, "max_devices": { "description": "Numero massimo di dispositivi simultanei o posti flottanti per licenza.", "type": "integer" }, "meter_rules": { "description": "Regole di misurazione delle funzionalità; vuoto indica che non ne è configurata alcuna.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Indica se sono consentiti utilizzi eccedenti della funzionalità.", "type": "boolean" }, "feature": { "description": "Identificativo di una funzionalità a consumo, che deve esistere nelle funzionalità della politica.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Utilizzo eccedente massimo consentito; disabilitato quando allow_overage è false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Istantanea di fatturazione mensile UTC predefinita; le regole di misurazione usano month/day/lifetime e le righe di utilizzo usano la chiave concreta del periodo.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" } }, "required": [ "mode", "max_devices", "features", "expires_at", "duration_days", "capabilities", "meter_rules" ], "type": "object" }, "blocked_reason": { "description": "Motivo per cui la modifica è bloccata; vuoto indica nessun impedimento attuale.", "type": "string" }, "customer": { "description": "Etichetta del cliente definita dal fornitore, distinta dall'email del portale clienti.", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } }, "required": [ "id", "customer", "before", "after", "blocked_reason", "active" ], "type": "object" }, "type": "array" }, "expires_in": { "const": 600, "description": "Durata del token di anteprima in secondi, attualmente 600.", "type": "integer" }, "note": { "description": "Ulteriori indicazioni per lo sviluppatore.", "type": "string" }, "policy_version": { "description": "Revisione della politica; inviare il valore corrente quando si modificano tutte le funzionalità per impedire scritture obsolete.", "type": "integer" }, "preview_token": { "description": "Token cifrato di conferma dell'anteprima obbligatorio per apply_policy; valido per 600 secondi e invalidato dalle modifiche alle risorse.", "type": "string" } }, "required": [ "changes", "policy_version", "preview_token", "expires_in", "note" ], "type": "object" }, "PolicySyncResult": { "additionalProperties": false, "properties": { "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "synced_licenses": { "description": "Numero di licenze collegate non revocate sincronizzate nella stessa transazione.", "minimum": 0, "type": "integer" } }, "required": [ "id", "synced_licenses" ], "type": "object" }, "PolicyUpdate": { "additionalProperties": false, "description": "Definisce la modalità di emissione, i limiti di dispositivi/posti, le funzionalità e le regole di esecuzione. Una politica non memorizza alcuna durata di validità.", "properties": { "features": { "description": "Fino a 32 identificatori distinti di funzionalità, ciascuno composto da 1–64 caratteri tra lettere ASCII, cifre, punti, trattini o trattini bassi.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita." }, { "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "0 disabilita esplicitamente gli heartbeat periodici; altrimenti 600–86400 secondi (minimo 10 minuti). Indipendente dalla durata offline consentita.", "type": "integer" }, "max_devices": { "description": "Numero massimo di dispositivi simultanei o posti flottanti per licenza.", "maximum": 10000, "minimum": 1, "type": "integer" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "Nome leggibile dall'utente; consultare i vincoli di lunghezza.", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "Durata offline consentita limited, none o permanent; la scadenza della licenza continua ad applicarsi.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Limited: 1–31536000 secondi e almeno 3 × heartbeat_seconds con gli heartbeat attivi; none/permanent: 0", "maximum": 31536000, "minimum": 0, "type": "integer" } }, "required": [], "type": "object" }, "PreviewInput": { "additionalProperties": false, "properties": { "ids": { "description": "UUID distinti delle licenze da elaborare, 1–100.", "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "policy_id": { "description": "UUID della politica; deve appartenere al prodotto al momento dell'emissione.", "format": "uuid", "type": "string" } }, "required": [ "policy_id", "ids" ], "type": "object" }, "Price": { "additionalProperties": false, "properties": { "api_hard_limit": { "description": "Indica se le chiamate di esecuzione si interrompono al raggiungimento della quota API.", "type": "boolean" }, "api_unit_micros": { "description": "Prezzo per chiamata di esecuzione eccedente, in milionesimi.", "minimum": 0, "type": "integer" }, "base_micros": { "description": "Addebito di base in milionesimi dell'unità valutaria.", "type": "integer" }, "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "type": "string" }, "description": { "description": "Descrizione dell'offerta di fatturazione.", "type": "string" }, "enabled": { "description": "Indica se l'offerta di fatturazione è abilitata all'acquisto.", "type": "boolean" }, "hard_limit": { "description": "Indica se i nuovi dispositivi fatturabili vengono rifiutati al raggiungimento della quota.", "type": "boolean" }, "included_api_calls": { "description": "null = illimitato; 0 = nessuna chiamata riuscita inclusa", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "description": "Quota inclusa di dispositivi attivi.", "type": "integer" }, "name": { "description": "Nome visualizzato dell'offerta di fatturazione.", "type": "string" }, "plan": { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "type": "string" }, "price_version": { "description": "Revisione del prezzo congelata; un input obsoleto può causare PLAN_VERSION_CONFLICT.", "type": "string" }, "public": { "description": "Indica se l'offerta di fatturazione è elencata pubblicamente.", "type": "boolean" }, "renewal_only": { "description": "I clienti esistenti con pacchetti pagati o regalati possono rinnovare in anticipo o dopo la scadenza nello stesso ambiente e nella stessa valuta. Nascosto dai nuovi acquisti pubblici.", "type": "boolean" }, "sort_order": { "description": "Ordine di visualizzazione dell'offerta di fatturazione.", "type": "integer" }, "terms": { "description": "Durate di acquisto disponibili e relativi prezzi.", "items": { "$ref": "#/components/schemas/PlanTermPrice" }, "type": "array" }, "unit_micros": { "description": "Prezzo per dispositivo attivo eccedente, in milionesimi.", "type": "integer" }, "updated_at": { "description": "Timestamp dell'ultimo aggiornamento in UTC.", "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "Product": { "additionalProperties": false, "example": { "created_at": "2026-10-18T00:00:00Z", "description": "Desktop reporting software", "id": "11111111-1111-4111-8111-111111111111", "name": "Report app", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "properties": { "created_at": { "description": "Timestamp di creazione, UTC ISO 8601.", "format": "date-time", "type": "string" }, "description": { "description": "Descrizione del prodotto.", "type": "string" }, "id": { "description": "UUID del prodotto usato nella configurazione dell'SDK e nella creazione delle politiche.", "format": "uuid", "type": "string" }, "name": { "description": "Nome del prodotto.", "maxLength": 120, "minLength": 1, "type": "string" }, "status": { "description": "active consente l'attivazione; disabled rifiuta le richieste di licenza in fase di esecuzione.", "enum": [ "active", "disabled" ], "type": "string" }, "updated_at": { "description": "Timestamp dell'ultimo aggiornamento, UTC ISO 8601.", "format": "date-time", "type": "string" } }, "required": [ "id", "name", "status" ], "type": "object" }, "ProductCreate": { "additionalProperties": false, "properties": { "description": { "description": "Descrizione software opzionale, fino a 1000 caratteri.", "maxLength": 1000, "type": "string" }, "name": { "description": "Nome del software, da 1 a 120 caratteri.", "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "ProductList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/Product" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "ProductUpdate": { "additionalProperties": false, "properties": { "description": { "description": "Descrizione del prodotto; può essere vuota.", "maxLength": 1000, "type": "string" }, "name": { "description": "Nome leggibile dall'utente; consultare i vincoli di lunghezza.", "maxLength": 120, "minLength": 1, "type": "string" }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "active", "disabled" ], "type": "string" } }, "required": [], "type": "object" }, "ProviderRefund": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "attempted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "attempts": { "minimum": 0, "type": "integer" }, "case_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "last_error": { "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "format": "uuid", "type": "string" }, "provider": { "enum": [ "waffo", "paddle" ], "type": "string" }, "provider_refund_id": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "reserved": { "type": "boolean" }, "settled_cents": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "created", "submitting", "pending", "unknown", "completed", "failed" ], "type": "string" }, "submitted_cents": { "minimum": 0, "type": "integer" }, "unapplied": { "type": "boolean" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "PurchaseList": { "additionalProperties": false, "properties": { "active": { "anyOf": [ { "$ref": "#/components/schemas/PlanPurchase", "description": "Indicatore della chiave di firma corrente; in un'anteprima della politica, numero di dispositivi/sessioni attivi." }, { "description": "Indicatore della chiave di firma corrente; in un'anteprima della politica, numero di dispositivi/sessioni attivi.", "type": "null" } ], "description": "Contratto del pacchetto acquistato attualmente effettivo oppure null." }, "active_devices": { "description": "Occupazione corrente dei prodotti/dispositivi registrati, indipendente dalla cronologia mensile degli utilizzi dei dispositivi. Le registrazioni ordinarie continuano a essere conteggiate offline fino al rilascio. Le sessioni flottanti vengono conteggiate soltanto finché i relativi lease sono validi e vengono deduplicate in base all'hardware, ripiegando sull'identità del dispositivo. Il rilascio o la scadenza dell'ultima sessione flottante restituisce capacità; le registrazioni valide proseguono oltre i confini dei mesi della quota. Le registrazioni isolate delle prove SDK sono escluse.", "type": "integer" }, "coverage_ends_at": { "anyOf": [ { "description": "Fine della copertura continua dei pacchetti pagati oppure null.", "format": "date-time", "type": "string" }, { "description": "Fine della copertura continua dei pacchetti pagati oppure null.", "type": "null" } ], "description": "Fine della copertura prepagata totale, inclusi i rinnovi anticipati pagati e i regali programmati. Il pacchetto attivo continua a riportare il proprio periodo corrente della quota." }, "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/PlanPurchase" }, "type": "array" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" }, "renewal_package": { "anyOf": [ { "$ref": "#/components/schemas/PlanPurchase", "description": "Ultimo contratto pagato idoneo al rinnovo oppure null." }, { "description": "Ultimo contratto pagato idoneo al rinnovo oppure null.", "type": "null" } ], "description": "Ultima copertura pagata o regalata, incluso l'upgrade applicato. Usare questo piano effettivo e la relativa valuta per selezionare il rinnovo manuale o automatico. Null finché non è stato attivato un pacchetto." }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [], "type": "object" }, "RechargeInput": { "additionalProperties": false, "description": "Collegare purchase_id OR upgrade_id, mai entrambi. Un pagamento confermato accredita il portafoglio e salda quell'acquisto/upgrade se il relativo preventivo è ancora valido. I pagamenti tardivi degli upgrade rimangono nel portafoglio.", "properties": { "amount": { "description": "Valore decimale della ricarica, massimo due cifre decimali", "type": "string" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "overage_accepted": { "description": "Autorizzazione esplicita separata degli sforamenti a pagamento visualizzati.", "type": "boolean" }, "policy_version": { "description": "Versione immutabile della politica attualmente pubblicata. Obbligatoria per le azioni protette dal consenso dopo che l'operatore ha pubblicato una politica, in entrambi gli ambienti di pagamento.", "type": "string" }, "purchase_id": { "format": "uuid", "type": [ "string", "null" ] }, "request_id": { "maxLength": 80, "type": "string" }, "terms_accepted": { "description": "Accettazione esplicita, non preselezionata per impostazione predefinita.", "type": "boolean" }, "upgrade_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } }, "required": [ "currency", "amount", "request_id" ], "type": "object" }, "RecoverOriginalRefund": { "additionalProperties": false, "properties": { "confirm_unpaid_manual": { "const": true, "type": "boolean" }, "expected_updated_at": { "format": "date-time", "type": "string" } }, "required": [ "confirm_unpaid_manual" ], "type": "object" }, "RefundHistory": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/RefundHistoryItem" }, "type": "array" }, "limit": { "minimum": 0, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "offset": { "minimum": 0, "type": "integer" }, "total": { "minimum": 0, "type": "integer" } }, "type": "object" }, "RefundHistoryItem": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "case_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "type": "string" }, "provider": { "enum": [ "paypal", "waffo", "paddle" ], "type": "string" }, "provider_refund_id": { "type": "string" }, "reason": { "type": "string" }, "settled_cents": { "minimum": 0, "type": "integer" }, "status": { "type": "string" } }, "type": "object" }, "RefundInboxItem": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "cancellation_scope": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "customer_email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "manual_refund_pending": { "type": "boolean" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "type": "string" }, "pending_review": { "type": "boolean" }, "purchase_id": { "type": "string" }, "reason": { "type": "string" }, "refund_totals": { "description": "Importi per valuta codificati in JSON per gli annullamenti con ambito definito.", "type": "string" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "scope": { "enum": [ "wallet", "service" ], "type": "string" }, "source": { "enum": [ "wallet_request", "support_case" ], "type": "string" }, "status": { "type": "string" }, "tenant_name": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "RefundInboxList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/RefundInboxItem" }, "type": "array" }, "limit": { "minimum": 0, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "offset": { "minimum": 0, "type": "integer" }, "summary": { "additionalProperties": false, "properties": { "pending_review": { "minimum": 0, "type": "integer" }, "service_pending_review": { "minimum": 0, "type": "integer" }, "wallet_pending_review": { "minimum": 0, "type": "integer" } }, "type": "object" }, "total": { "minimum": 0, "type": "integer" } }, "type": "object" }, "RefundInput": { "additionalProperties": false, "properties": { "amount": { "description": "Importo positivo del rimborso nella valuta dell'acquisizione; non può superare i fondi acquisiti rimanenti o il credito disponibile e non speso del portafoglio.", "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "reason": { "maxLength": 255, "minLength": 1, "type": "string" }, "request_id": { "maxLength": 80, "minLength": 1, "type": "string" } }, "required": [ "amount", "reason", "request_id" ], "type": "object" }, "RefundList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PayPalRefund" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "RefundQuote": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "automatic_entitlement_cancellation": { "type": "boolean" }, "currency": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "requires_confirmation": { "type": "boolean" } }, "required": [], "type": "object" }, "RefundReview": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "amounts": { "items": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" } }, "required": [ "purchase_id", "amount" ], "type": "object" }, "type": "array" }, "approve": { "type": "boolean" }, "decision": { "maxLength": 3000, "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" } }, "required": [ "approve", "decision" ], "type": "object" }, "Register": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "overage_accepted": { "description": "Autorizzazione esplicita separata degli sforamenti a pagamento visualizzati.", "type": "boolean" }, "password": { "description": "12–128 byte UTF-8, non caratteri", "type": "string", "writeOnly": true }, "password_confirmation": { "description": "Obbligatorio e deve corrispondere esattamente a password", "type": "string", "writeOnly": true }, "policy_version": { "description": "Versione immutabile della politica attualmente pubblicata. Obbligatoria per le azioni protette dal consenso dopo che l'operatore ha pubblicato una politica, in entrambi gli ambienti di pagamento.", "type": "string" }, "tenant_name": { "maxLength": 120, "minLength": 1, "type": "string" }, "terms_accepted": { "description": "Accettazione esplicita, non preselezionata per impostazione predefinita.", "type": "boolean" } }, "required": [ "email", "password", "password_confirmation", "name", "tenant_name" ], "type": "object" }, "Release": { "additionalProperties": false, "example": { "channel": "stable", "created_at": "2026-10-18T00:00:00Z", "download_url": "", "id": "33333333-3333-4333-8333-333333333333", "notes": "Initial release", "product_id": "11111111-1111-4111-8111-111111111111", "published_at": "2026-10-18T00:00:00Z", "sha256": "", "version": "1.0.0" }, "properties": { "channel": { "description": "Canale di release, stable o preview; il valore predefinito è stable.", "type": "string" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "download_url": { "description": "URL di download HTTPS; sha256 è obbligatorio quando viene fornito un URL.", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "notes": { "description": "Note sulla versione", "type": "string" }, "product_id": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" }, "published_at": { "description": "Timestamp di pubblicazione della release, UTC; il valore predefinito è l'orario del server.", "format": "date-time", "type": "string" }, "sha256": { "description": "SHA-256 del file scaricabile, 64 caratteri esadecimali minuscoli, distinto dall'algoritmo di firma.", "type": "string" }, "version": { "description": "Revisione della politica, versione major.minor.patch del prodotto o versione 1 del protocollo offline, a seconda dell'oggetto.", "type": "string" } }, "required": [ "id", "product_id", "version", "channel", "notes", "download_url", "sha256", "published_at", "created_at" ], "type": "object" }, "ReleaseInput": { "additionalProperties": false, "properties": { "channel": { "description": "Canale di release, stable o preview; il valore predefinito è stable.", "enum": [ "stable", "preview" ], "type": "string" }, "download_url": { "description": "URL di download HTTPS; sha256 è obbligatorio quando viene fornito un URL.", "format": "uri", "maxLength": 2000, "type": "string" }, "notes": { "description": "Note sulla versione", "maxLength": 10000, "type": "string" }, "published_at": { "description": "Timestamp di pubblicazione della release, UTC; il valore predefinito è l'orario del server.", "format": "date-time", "type": "string" }, "sha256": { "description": "SHA-256 del file scaricabile, 64 caratteri esadecimali minuscoli, distinto dall'algoritmo di firma.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "version": { "description": "Revisione della politica, versione major.minor.patch del prodotto o versione 1 del protocollo offline, a seconda dell'oggetto.", "pattern": "^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" } }, "required": [ "version" ], "type": "object" }, "ReleaseList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/Release" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "Renew": { "additionalProperties": false, "properties": { "days": { "description": "Giorni aggiuntivi, 1–36500; i rinnovi delle licenze e quelli della manutenzione modificano termini diversi.", "maximum": 36500, "minimum": 1, "type": "integer" } }, "required": [ "days" ], "type": "object" }, "RenewalPlans": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/Price" }, "type": "array" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "items", "mode" ], "type": "object" }, "Renewed": { "additionalProperties": false, "example": { "duration_days": 60, "expires_at": null, "id": "33333333-3333-4333-8333-333333333333" }, "properties": { "duration_days": { "description": "I rinnovi precedenti alla prima attivazione incrementano questo valore. Dopo l'attivazione mantiene la durata originale; usare expires_at per la scadenza effettiva.", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "format": "date-time", "type": "string" }, { "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale.", "type": "null" } ], "description": "Scadenza della licenza; null per licenze timed/trial non attivate o licenze perpetual. Negli oggetti delle chiavi indica la scadenza della credenziale." }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } }, "required": [ "id", "expires_at", "duration_days" ], "type": "object" }, "ReservationResult": { "additionalProperties": false, "properties": { "activation_id": { "description": "UUID dell'associazione del dispositivo o della sessione di esecuzione. Conservarlo per le future richieste di licenza; non è una chiave di licenza.", "format": "uuid", "type": "string" }, "heartbeat_seconds": { "anyOf": [ { "const": 0 }, { "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Intervallo corrente dell'heartbeat in secondi; la misurazione non aggiorna la firma né il timer.", "type": "integer" }, "reservation": { "$ref": "#/components/schemas/FeatureReservation" } }, "required": [ "activation_id", "reservation" ], "type": "object" }, "Revenue": { "additionalProperties": false, "properties": { "invoices": { "items": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "month": { "type": "string" }, "paid_at": { "format": "date-time", "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "refunded_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "tenant_name": { "type": "string" }, "total_cents": { "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "limit": { "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "month": { "type": "string" }, "offset": { "type": "integer" }, "paddle_totals": { "description": "Pagamenti lordi e rimborsi cumulativi sia per acquisti di servizi sia per ricariche del portafoglio, raggruppati per mese del pagamento originale e valuta; non è un regolamento bancario.", "items": { "additionalProperties": false, "properties": { "currency": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" }, "paid_cents": { "description": "Prezzo completo del servizio congelato nell'unità monetaria minima; nessuna ricarica del portafoglio o pagamento misto.", "type": "integer" }, "refunded_cents": { "description": "Prezzo completo del servizio congelato nell'unità monetaria minima; nessuna ricarica del portafoglio o pagamento misto.", "type": "integer" } }, "required": [ "currency", "paid_cents", "refunded_cents" ], "type": "object" }, "type": "array" }, "paid_users": { "type": "integer" }, "purchase_total": { "type": "integer" }, "purchases": { "items": { "additionalProperties": false, "properties": { "api_calls": { "type": "integer" }, "api_overage_cents": { "type": "integer" }, "base_cents": { "type": "integer" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "email": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "overage_cents": { "type": "integer" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "plan_name": { "type": "string" }, "source": { "enum": [ "purchase", "gift" ], "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "pending", "active", "cancelled" ], "type": "string" }, "tenant_name": { "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "recharged_users": { "type": "integer" }, "registered_users": { "type": "integer" }, "sales": { "items": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "quantity": { "type": "integer" }, "total_cents": { "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "sold_subscriptions": { "type": "integer" }, "timezone": { "type": "string" }, "topup_total": { "type": "integer" }, "topups": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "credited_at": { "format": "date-time", "type": "string" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "provider": { "description": "Fornitore originale della ricarica del portafoglio; i rimborsi rimangono legati a questo fornitore.", "enum": [ "paypal", "paddle", "waffo" ], "type": "string" }, "refunded_cents": { "type": "integer" }, "status": { "type": "string" }, "tenant_name": { "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "total": { "type": "integer" }, "totals": { "items": { "additionalProperties": false, "properties": { "consumption_cents": { "type": "integer" }, "consumption_refund_cents": { "type": "integer" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "paypal_refund_cents": { "type": "integer" }, "recharge_cents": { "type": "integer" }, "wallet_refund_cents": { "description": "Rimborsi/storni del portafoglio eseguiti tramite PayPal, Paddle e Waffo; esclude i blocchi temporanei per rimborsi.", "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "upgrade_total": { "description": "Numero di upgrade applicati nell'ambiente e nel periodo di rendicontazione selezionati, inclusi quelli gratuiti. Conteggiati separatamente dalle vendite iniziali dei pacchetti.", "type": "integer" }, "upgrades": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Importo effettivamente pagato calcolato pro rata; non il nuovo prezzo mensile completo.", "type": "integer" }, "applied_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "email": { "type": "string" }, "ends_at": { "description": "Scadenza originale del pacchetto, invariata dall'upgrade.", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "plan_name": { "description": "Nome del pacchetto di destinazione.", "type": "string" }, "previous_plan_name": { "description": "Pacchetto effettivo prima di questo upgrade.", "type": "string" }, "tenant_name": { "type": "string" } }, "required": [ "id", "email", "tenant_name", "plan_name", "previous_plan_name", "currency", "amount_cents", "applied_at", "ends_at" ], "type": "object" }, "type": "array" }, "waffo_totals": { "description": "Pagamenti lordi e rimborsi cumulativi sia per acquisti di servizi sia per ricariche del portafoglio, raggruppati per mese del pagamento originale e valuta; non è un regolamento bancario.", "items": { "additionalProperties": false, "properties": { "currency": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "paid_cents": { "description": "Prezzo completo del servizio congelato nell'unità monetaria minima; nessuna ricarica del portafoglio o pagamento misto.", "type": "integer" }, "refunded_cents": { "description": "Prezzo completo del servizio congelato nell'unità monetaria minima; nessuna ricarica del portafoglio o pagamento misto.", "type": "integer" } }, "required": [ "currency", "paid_cents", "refunded_cents" ], "type": "object" }, "type": "array" } }, "required": [], "type": "object" }, "RuntimeAPIPeriod": { "additionalProperties": false, "properties": { "api_calls": { "description": "Chiamate API di esecuzione a consumo riuscite nell'ambito; le richieste amministrative sono escluse.", "type": "integer" }, "api_hard_limit": { "description": "Indica se le chiamate di esecuzione si interrompono al raggiungimento della quota API.", "type": "boolean" }, "api_overage_cents": { "description": "Addebito per sforamento API in centesimi in questo ciclo.", "type": "integer" }, "api_unit_micros": { "description": "Prezzo per chiamata di esecuzione eccedente, in milionesimi.", "minimum": 0, "type": "integer" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "included_api_calls": { "description": "null = illimitato; 0 = nessuna chiamata riuscita inclusa", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" }, "month": { "description": "Mese UTC YYYY-MM; i valori di query omessi usano il mese corrente. Le attività di fatturazione richiedono un mese concluso.", "type": "string" }, "plan": { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "price_version": { "description": "Revisione del prezzo congelata; un input obsoleto può causare PLAN_VERSION_CONFLICT.", "type": "string" } }, "required": [], "type": "object" }, "RuntimeInput": { "additionalProperties": false, "properties": { "activation_id": { "description": "data.activation_id dall'ultima attivazione riuscita. Obbligatorio per convalida, heartbeat, consume e disattivazione; omettere soltanto al primo activate.", "format": "uuid", "type": "string" }, "app_version": { "description": "Versione corrente dell'app, major.minor.patch, ad es. 1.0.0. Obbligatorio per la manutenzione o le regole sull'intervallo di versioni. Non segnalare erroneamente un'app più recente come una versione precedente.", "pattern": "^$|^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "device_id": { "description": "Hash SHA-256 di 64 caratteri esadecimali minuscoli, calcolato dall'SDK a partire dalle identità di prodotto, sistema e hardware. Non sostituirlo con un valore fisso.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "device_name": { "description": "Nome visualizzato nel dashboard, fino a 120 caratteri. Non determina l'identità del dispositivo.", "maxLength": 120, "type": "string" }, "device_profile": { "$ref": "#/components/schemas/DeviceProfile", "description": "Profilo della macchina generato dall'SDK. Fornirlo secondo i requisiti delle politiche per l'identità hardware, il rifiuto delle VM o la migrazione hardware." }, "environment": { "description": "Ambiente commerciale, fissato sia nella connessione sia nell'autorizzazione firmata.", "enum": [ "live", "sandbox" ], "type": "string" }, "feature": { "description": "Identificativo della funzionalità consumata.", "maxLength": 64, "type": "string" }, "identity_token": { "description": "JWT di identità Launch Ed25519 tipizzato e monouso; nessuna dichiarazione sui diritti viene considerata attendibile come diritto di acquisto.", "maxLength": 12288, "type": "string", "writeOnly": true }, "launch_connection_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "license_key": { "description": "Chiave completa del cliente: lv_lic_ è una chiave di licenza ordinaria; lv_tmp_ serve per il riscatto iniziale del trasferimento. Dopo il successo, l'SDK usa una credenziale lv_dev_ vincolata alla macchina. Non è una API Key amministrativa del fornitore.", "pattern": "^(?:lv_(?:lic|tmp|dev)_[A-Za-z0-9_-]{43})?$", "type": "string", "writeOnly": true }, "product_id": { "description": "UUID del prodotto; deve corrispondere al prodotto della licenza.", "format": "uuid", "type": "string" }, "quantity": { "description": "Unità richieste per questa operazione, numero intero 1–1000000000.", "maximum": 1000000000, "minimum": 1, "type": "integer" }, "request_logout_ticket": { "description": "Negoziazione delle funzionalità dell'SDK. Richiedere un ticket di disconnessione riservato allo scollegamento quando non è conservato alcun ticket per l'associazione corrente. Ometterlo quando è già conservato un ticket di disconnessione valido; gli heartbeat a regime evitano una ricerca aggiuntiva del ticket.", "type": "boolean" }, "reservation_id": { "description": "ID della prenotazione; invia questo valore per confermare o annullare.", "format": "uuid", "type": "string" }, "reservation_seconds": { "default": 900, "description": "Durata facoltativa della prenotazione, 30–3600 secondi; valore predefinito 900. Termina prima se interviene l'azzeramento del periodo.", "maximum": 3600, "minimum": 30, "type": "integer" }, "session_id": { "description": "Obbligatorio per le licenze flottanti: generare un UUID per ogni istanza in esecuzione e riutilizzarlo nelle richieste di quell'istanza. Facoltativo per le licenze vincolate al dispositivo.", "format": "uuid", "type": "string" } }, "required": [ "product_id", "license_key", "device_id" ], "type": "object" }, "RuntimePolicy": { "additionalProperties": false, "properties": { "heartbeat_seconds": { "anyOf": [ { "const": 0 }, { "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Intervallo di heartbeat online, in secondi. 0 disabilita gli heartbeat periodici. La durata offline consentita si configura separatamente.", "type": "integer" }, "offline_mode": { "description": "limited: uso offline a tempo limitato; none: nessun uso offline; permanent: nessun limite temporale offline aggiuntivo, ma la scadenza della licenza continua ad applicarsi.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Secondi offline consentiti: 1–31536000 per limited, 0 per none/permanent. Non è l'intervallo di heartbeat. Con gli heartbeat attivi, le nuove politiche offline limitate devono rispettare offline_seconds \u003e= 3 × heartbeat_seconds; anche i lease delle licenze flottanti devono coprire almeno tre intervalli di heartbeat.", "maximum": 31536000, "minimum": 0, "type": "integer" } }, "required": [ "heartbeat_seconds", "offline_mode", "offline_seconds" ], "type": "object" }, "RuntimeResult": { "additionalProperties": false, "properties": { "activation_id": { "description": "UUID dell'associazione del dispositivo o della sessione di esecuzione. Conservarlo per le future richieste di licenza; non è una chiave di licenza.", "format": "uuid", "type": "string" }, "deactivated": { "description": "true in caso di disattivazione riuscita. Rilascia un'associazione o una sessione; non elimina la licenza né ne reimposta la durata.", "type": "boolean" }, "device_key": { "description": "Credenziale del dispositivo limitata e vincolata al dispositivo e alla versione dell'associazione. Le credenziali in modalità account richiedono inoltre una sessione di autorizzazione attiva e un diritto valido; non possono riattivare un'associazione rilasciata.", "pattern": "^lv_dev_[A-Za-z0-9_-]{43}$", "type": "string" }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita." }, { "description": "Intervallo di heartbeat in secondi: 0 lo disabilita; altrimenti 600–86400. L'omissione usa i valori predefiniti del server; indipendente dalla durata offline consentita.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Intervallo di heartbeat suggerito, in secondi. Il campo al livello principale può essere omesso per 0; runtime_policy.heartbeat_seconds nella firma è il valore autorevole della politica.", "type": "integer" }, "lease": { "$ref": "#/components/schemas/Lease", "description": "Cache della licenza firmata dal server. Accettarla soltanto dopo la verifica con una chiave pubblica attendibile fissata e il controllo di prodotto/dispositivo. Non viene restituita dalla disattivazione o da consume." }, "logout_ticket": { "$ref": "#/components/schemas/LogoutTicket", "description": "Facoltà riservata allo scollegamento di questa precisa incarnazione dell'associazione; non includerla nei log delle richieste di esecuzione." } }, "required": [ "activation_id" ], "type": "object" }, "SDKConfig": { "additionalProperties": false, "example": { "allow_http": false, "app_version": "", "base_url": "https://www.licentivo.com", "cache_path": "", "device_name": "My application", "license_key": "", "product_id": "11111111-1111-4111-8111-111111111111", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "properties": { "allow_http": { "description": "Indica se HTTP è consentito, soltanto per lo sviluppo locale.", "type": "boolean" }, "app_version": { "description": "Versione major.minor.patch corrente del software.", "type": "string" }, "base_url": { "description": "Origine del server delle licenze, normalmente HTTPS, senza /api/v1.", "type": "string" }, "cache_path": { "description": "Percorso della cache locale; un valore vuoto lascia all'SDK la scelta di una directory privata dell'utente.", "type": "string" }, "device_name": { "description": "Etichetta del dispositivo leggibile dall'utente, non un'identità di sicurezza.", "type": "string" }, "license_key": { "description": "Chiave di licenza completa del cliente fornita all'attivazione. Il codice di inizializzazione del prodotto e gli esempi scaricabili non contengono questo segreto. Le richieste offline usano la credenziale fornita dall'SDK.", "type": "string" }, "product_id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "trusted_keys": { "additionalProperties": { "type": "string" }, "description": "Mappa dall'UUID della chiave pubblica alla chiave pubblica Base64URL per la verifica con chiavi fissate.", "type": "object" } }, "required": [ "base_url", "product_id", "license_key", "app_version", "device_name", "trusted_keys", "cache_path", "allow_http" ], "type": "object" }, "SDKExampleInfo": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "can_configure": { "type": "boolean" }, "duration_days": { "const": 3, "type": "integer" }, "starts_at_first_activation": { "type": "boolean" } }, "required": [], "type": "object" }, "SDKExampleSetting": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "duration_days": { "const": 3, "type": "integer" }, "policy_id": { "description": "UUID della politica dedicata; vuoto prima della configurazione iniziale.", "type": "string" }, "product_id": { "description": "UUID del prodotto dedicato; vuoto prima della configurazione iniziale.", "type": "string" } }, "required": [ "available", "duration_days", "product_id", "policy_id" ], "type": "object" }, "SDKExampleSetup": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": [], "type": "object" }, "SDKExampleTrial": { "additionalProperties": false, "properties": { "duration_days": { "const": 3, "type": "integer" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "first_activated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "license_key": { "type": "string" }, "starts_at_first_activation": { "type": "boolean" }, "status": { "type": "string" } }, "required": [], "type": "object" }, "SDKInitializer": { "additionalProperties": false, "example": { "language": "go", "product_id": "11111111-1111-4111-8111-111111111111", "source": "const productID = \"11111111-1111-4111-8111-111111111111\"\nvar trustedKeys = map[string]string{\"66666666-6666-4666-8666-666666666666\": \"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"}\n", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "properties": { "language": { "description": "Identificativo del linguaggio SDK per il bundle scaricabile.", "type": "string" }, "product_id": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" }, "source": { "description": "Costanti pubbliche del prodotto da incollare nel codice; nessun segreto di attivazione del cliente.", "type": "string" }, "trusted_keys": { "additionalProperties": { "type": "string" }, "description": "Mappa dall'UUID della chiave pubblica alla chiave pubblica Base64URL per la verifica con chiavi fissate.", "type": "object" } }, "required": [ "product_id", "trusted_keys", "language", "source" ], "type": "object" }, "ScheduledPlan": { "additionalProperties": false, "properties": { "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "type": "string" }, "effective_month": { "description": "Mese UTC YYYY-MM in cui la pianificazione diventa effettiva.", "type": "string" }, "plan": { "description": "Identificativo stabile del piano di fatturazione dal catalogo pubblicato.", "type": "string" }, "sandbox": { "description": "Ambiente di test", "type": "boolean" } }, "required": [], "type": "object" }, "ScopedRefundPreview": { "additionalProperties": false, "properties": { "affected_purchases": { "items": { "$ref": "#/components/schemas/ScopedRefundPurchase" }, "type": "array" }, "auto_renewal_disabled": { "type": "boolean" }, "auto_renewal_enabled": { "type": "boolean" }, "cancellation_at": { "const": "approval", "type": "string" }, "pending_purchase_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "pending_upgrade_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "remaining_purchases": { "items": { "$ref": "#/components/schemas/ScopedRefundPurchase" }, "type": "array" }, "request": { "$ref": "#/components/schemas/CustomerRefundInput" }, "scope": { "enum": [ "purchase", "service" ], "type": "string" }, "totals": { "items": { "$ref": "#/components/schemas/ScopedRefundTotal" }, "type": "array" } }, "required": [], "type": "object" }, "ScopedRefundPurchase": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "approved_cents": { "type": "integer" }, "currency": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "maximum_cents": { "type": "integer" }, "plan_name": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "requires_review": { "type": "boolean" }, "source": { "type": "string" }, "starts_at": { "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "ScopedRefundTotal": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "approved_cents": { "type": "integer" }, "currency": { "type": "string" }, "held_cents": { "type": "integer" }, "manual_cents": { "type": "integer" } }, "required": [], "type": "object" }, "ServiceCompensation": { "additionalProperties": false, "properties": { "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "incident_id": { "description": "UUID dell'incidente di servizio correlato.", "format": "uuid", "type": "string" }, "intervals": { "description": "Intervalli temporali compensati restituiti come stringa JSON.", "type": "string" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "type": "string" }, "purchase_id": { "description": "UUID dell'acquisto di pacchetto correlato.", "format": "uuid", "type": "string" }, "seconds": { "description": "Secondi aggiunti come compensazione del servizio.", "type": "integer" } }, "required": [ "id", "incident_id", "mode", "seconds", "purchase_id", "created_at" ], "type": "object" }, "ServiceCompensationList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/ServiceCompensation" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "ServiceIncident": { "additionalProperties": false, "properties": { "affected_tenants": { "description": "Array di ID degli spazi di lavoro codificato in JSON; [] indica globale.", "type": "string" }, "body": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "emergency": { "type": "boolean" }, "ends_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "ServiceIncidentInput": { "additionalProperties": false, "properties": { "affected_tenants": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "body": { "type": "string" }, "emergency": { "type": "boolean" }, "ends_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "expected_version": { "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "maintenance", "incident" ], "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "title": { "type": "string" } }, "required": [ "kind", "title", "body", "starts_at" ], "type": "object" }, "ServiceIncidentList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ServiceIncident" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "SignedCapabilities": { "additionalProperties": false, "properties": { "app_version": { "description": "Versione dell'applicazione per questa operazione di autorizzazione Launch.", "pattern": "^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "binding_version": { "description": "Generazione firmata dell'associazione del dispositivo, associata alla sessione di autorizzazione.", "minimum": 1, "type": "integer" }, "environment": { "description": "Ambiente commerciale, fissato sia nella connessione sia nell'autorizzazione firmata.", "enum": [ "live", "sandbox" ], "type": "string" }, "launch_connection_id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "license_model": { "description": "Modello di licenza per questa operazione di autorizzazione Launch.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_until": { "description": "Termine della manutenzione per questa operazione di autorizzazione Launch.", "type": "integer" }, "session_expires_at": { "description": "Scadenza della sessione per questa operazione di autorizzazione Launch.", "maximum": 253402300799, "type": "integer" }, "session_id": { "description": "ID della sessione per questa operazione di autorizzazione Launch.", "format": "uuid", "type": "string" }, "version_released_at": { "description": "Data di rilascio della versione per questa operazione di autorizzazione Launch.", "type": "integer" } }, "required": [ "license_model" ], "type": "object" }, "SigningKey": { "additionalProperties": false, "properties": { "active": { "description": "Indicatore della chiave di firma corrente; in un'anteprima della politica, numero di dispositivi/sessioni attivi.", "type": "boolean" }, "algorithm": { "const": "Ed25519", "description": "Algoritmo di firma, attualmente Ed25519.", "type": "string" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "key_id": { "description": "UUID della chiave di firma del prodotto usato per selezionare una chiave di verifica.", "format": "uuid", "type": "string" }, "public_key": { "description": "Chiave pubblica Ed25519 codificata in Base64URL; nessun materiale privato.", "type": "string" }, "retired_at": { "anyOf": [ { "description": "Timestamp del ritiro della chiave; null per le chiavi correnti. Le chiavi pubbliche ritirate rimangono disponibili per la verifica.", "format": "date-time", "type": "string" }, { "description": "Timestamp del ritiro della chiave; null per le chiavi correnti. Le chiavi pubbliche ritirate rimangono disponibili per la verifica.", "type": "null" } ], "description": "Timestamp del ritiro della chiave; null per le chiavi correnti. Le chiavi pubbliche ritirate rimangono disponibili per la verifica." } }, "required": [ "key_id", "public_key", "active" ], "type": "object" }, "StateResult": { "additionalProperties": false, "example": { "id": "33333333-3333-4333-8333-333333333333", "status": "pending" }, "properties": { "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "Subscription": { "additionalProperties": false, "properties": { "current": { "$ref": "#/components/schemas/Period", "description": "Istantanea di fatturazione predefinita per il mese UTC corrente." }, "next": { "anyOf": [ { "$ref": "#/components/schemas/PendingPlan", "description": "Piano predefinito programmato per il mese successivo oppure null." }, { "description": "Piano predefinito programmato per il mese successivo oppure null.", "type": "null" } ], "description": "Piano predefinito programmato per il mese successivo oppure null." }, "sandbox": { "description": "Questa anteprima dell'abbonamento restituisce true. Determinare l'ambiente di pagamento effettivo dalle impostazioni di fatturazione/pagamento, non da questo indicatore di anteprima.", "type": "boolean" } }, "required": [], "type": "object" }, "Summary": { "additionalProperties": false, "properties": { "active_licenses": { "description": "Numero di licenze attive e non scadute, incluse quelle in attesa della prima attivazione.", "type": "integer" }, "licenses": { "description": "Numero di licenze non archiviate.", "type": "integer" }, "policies": { "description": "Numero di politiche non archiviate.", "type": "integer" }, "products": { "description": "Conteggio dei prodotti nel riepilogo; gruppi di utilizzo dei dispositivi per prodotto nelle risposte sull'utilizzo.", "type": "integer" } }, "required": [ "products", "policies", "licenses", "active_licenses" ], "type": "object" }, "SupportCase": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "approved_cents": { "type": "integer" }, "cancellation_preview": { "description": "Anteprima dell'annullamento codificata in JSON.", "type": "string" }, "cancellation_scope": { "type": "string" }, "change_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "decision": { "type": "string" }, "first_response_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "held_cents": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "incident_id": { "type": "string" }, "kind": { "type": "string" }, "manual_cents": { "type": "integer" }, "manual_refund_pending": { "type": "boolean" }, "mode": { "type": "string" }, "order_id": { "type": "string" }, "purchase_id": { "type": "string" }, "reason": { "type": "string" }, "refund_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "refund_totals": { "description": "Totali per valuta codificati in JSON; non sommare mai valute diverse.", "type": "string" }, "request_id": { "type": "string" }, "response_due_at": { "format": "date-time", "type": "string" }, "review_due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "scope_ids": { "type": "string" }, "status": { "type": "string" }, "subject": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "SupportCaseDetail": { "additionalProperties": false, "properties": { "case": { "$ref": "#/components/schemas/SupportCase" }, "messages": { "items": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "case_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "staff": { "type": "boolean" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "original_refund_receipts": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "currency": { "type": "string" }, "intent_id": { "format": "uuid", "type": "string" }, "refund_id": { "type": "string" } }, "type": "object" }, "type": "array" }, "original_refunds": { "items": { "$ref": "#/components/schemas/ProviderRefund" }, "type": "array" }, "refund_payments": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "provider": { "type": "string" }, "provider_order_id": { "type": "string" }, "refunded_cents": { "minimum": 0, "type": "integer" }, "status": { "type": "string" } }, "type": "object" }, "type": "array" }, "refund_provider": { "type": "string" }, "refund_unverified": { "type": "boolean" }, "refunds": { "items": { "$ref": "#/components/schemas/PayPalRefund" }, "type": "array" } }, "required": [], "type": "object" }, "SupportCaseInput": { "additionalProperties": false, "properties": { "body": { "maxLength": 10000, "type": "string" }, "kind": { "enum": [ "support", "privacy", "appeal" ], "type": "string" }, "request_id": { "maxLength": 80, "type": "string" }, "subject": { "maxLength": 200, "type": "string" } }, "required": [ "subject", "body", "request_id" ], "type": "object" }, "SupportCaseList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/SupportCase" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "SupportContact": { "additionalProperties": false, "properties": { "email": { "description": "Email pubblica dell'assistenza e Reply-To per le email di fatturazione. Un valore vuoto nasconde il contatto. Non modifica l'indirizzo SMTP From esistente né crea una casella di posta.", "maxLength": 254, "type": "string" } }, "required": [ "email" ], "type": "object" }, "SupportReadInput": { "additionalProperties": false, "properties": { "last_message_id": { "format": "uuid", "type": "string" } }, "required": [ "last_message_id" ], "type": "object" }, "SupportReply": { "additionalProperties": false, "properties": { "body": { "maxLength": 10000, "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "", "reviewing", "awaiting_info", "resolved" ], "type": "string" } }, "required": [ "body" ], "type": "object" }, "SupportUnread": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "case_id": { "format": "uuid", "type": "string" }, "unread_messages": { "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "unread_cases": { "type": "integer" }, "unread_messages": { "type": "integer" }, "unread_notices": { "type": "integer" } }, "required": [], "type": "object" }, "SystemSettings": { "additionalProperties": false, "properties": { "database": { "$ref": "#/components/schemas/DatabaseStatus" }, "environment": { "type": "string" }, "mail": { "$ref": "#/components/schemas/MailSettings" }, "public_url": { "format": "uri", "type": "string" } }, "required": [ "mail", "database" ], "type": "object" }, "TLSCertificateInfo": { "additionalProperties": false, "properties": { "algorithm": { "type": "string" }, "chain_length": { "maximum": 10, "minimum": 1, "type": "integer" }, "domains": { "items": { "type": "string" }, "type": "array" }, "fingerprint_sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "issuer": { "type": "string" }, "not_after": { "format": "date-time", "type": "string" }, "not_before": { "format": "date-time", "type": "string" }, "self_signed": { "type": "boolean" }, "serial_number": { "type": "string" }, "subject": { "type": "string" } }, "required": [ "domains", "subject", "issuer", "not_before", "not_after", "fingerprint_sha256", "serial_number", "algorithm", "chain_length", "self_signed" ], "type": "object" }, "TLSCertificateInput": { "additionalProperties": false, "properties": { "certificate_pem": { "description": "Certificato finale PEM seguito dai certificati intermedi, nell'ordine corretto. Deve corrispondere a public_url. Solo lo sviluppo locale consente un certificato autofirmato.", "maxLength": 32768, "type": "string", "writeOnly": true }, "expected_version": { "description": "Usare version da GET /system/tls. Obbligatorio per gli aggiornamenti; una sostituzione concorrente restituisce 409.", "type": "string" }, "private_key_pem": { "description": "Chiave PEM non cifrata corrispondente (PKCS#8, RSA o EC). Non viene mai restituita da alcuna risposta.", "maxLength": 16384, "type": "string", "writeOnly": true } }, "required": [ "certificate_pem", "private_key_pem" ], "type": "object" }, "TLSCertificateResult": { "additionalProperties": false, "properties": { "certificate": { "$ref": "#/components/schemas/TLSCertificateInfo" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "certificate", "version", "updated_at" ], "type": "object" }, "TLSCertificateUpdateInput": { "additionalProperties": false, "properties": { "certificate_pem": { "description": "Certificato finale PEM seguito dai certificati intermedi, nell'ordine corretto. Deve corrispondere a public_url. Solo lo sviluppo locale consente un certificato autofirmato.", "maxLength": 32768, "type": "string", "writeOnly": true }, "expected_version": { "description": "Usare version da GET /system/tls. Obbligatorio per gli aggiornamenti; una sostituzione concorrente restituisce 409.", "type": "string" }, "private_key_pem": { "description": "Chiave PEM non cifrata corrispondente (PKCS#8, RSA o EC). Non viene mai restituita da alcuna risposta.", "maxLength": 16384, "type": "string", "writeOnly": true } }, "required": [ "certificate_pem", "private_key_pem", "expected_version" ], "type": "object" }, "TLSStatus": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "certificate": { "anyOf": [ { "$ref": "#/components/schemas/TLSCertificateInfo" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "http_redirect_address": { "type": "string" }, "public_url": { "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "version": { "type": "string" } }, "required": [ "enabled", "public_url", "address", "http_redirect_address", "certificate", "version", "updated_at" ], "type": "object" }, "TestMail": { "additionalProperties": false, "properties": { "to": { "format": "email", "type": "string" } }, "required": [ "to" ], "type": "object" }, "Token": { "additionalProperties": false, "properties": { "token": { "maxLength": 100, "minLength": 32, "type": "string", "writeOnly": true } }, "required": [ "token" ], "type": "object" }, "TokenPassword": { "additionalProperties": false, "properties": { "password": { "description": "12–128 byte UTF-8, non caratteri", "type": "string", "writeOnly": true }, "password_confirmation": { "description": "Obbligatorio e deve corrispondere esattamente a password", "type": "string", "writeOnly": true }, "token": { "maxLength": 100, "minLength": 32, "type": "string", "writeOnly": true } }, "required": [ "token", "password", "password_confirmation" ], "type": "object" }, "TransferCode": { "additionalProperties": false, "properties": { "activation_code": { "pattern": "^lv_tmp_[A-Za-z0-9_-]{43}$", "type": "string" }, "activation_id": { "format": "uuid", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "license_id": { "format": "uuid", "type": "string" } }, "required": [ "activation_id", "activation_code", "expires_at", "license_id" ], "type": "object" }, "TranslationCheck": { "additionalProperties": false, "properties": { "connected": { "type": "boolean" }, "languages": { "items": { "$ref": "#/components/schemas/TranslationLanguage" }, "type": "array" }, "provider_usage": { "additionalProperties": false, "properties": { "character_count": { "type": "integer" }, "character_limit": { "type": "integer" } }, "required": [ "character_count", "character_limit" ], "type": "object" } }, "required": [ "connected", "languages", "provider_usage" ], "type": "object" }, "TranslationLanguage": { "additionalProperties": false, "properties": { "lang": { "description": "Codice di destinazione BCP 47 restituito da DeepL v3, ad esempio en-US o zh-Hant.", "type": "string" }, "name": { "type": "string" }, "usable_as_target": { "type": "boolean" } }, "required": [ "lang", "name", "usable_as_target" ], "type": "object" }, "TranslationOptions": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "languages": { "items": { "$ref": "#/components/schemas/TranslationLanguage" }, "type": "array" }, "provider": { "type": "string" } }, "required": [ "enabled", "languages", "provider" ], "type": "object" }, "TranslationSettings": { "additionalProperties": false, "properties": { "checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "key_configured": { "type": "boolean" }, "languages": { "items": { "$ref": "#/components/schemas/TranslationLanguage" }, "type": "array" }, "local_usage": { "$ref": "#/components/schemas/TranslationUsage" }, "monthly_limit": { "description": "Budget mensile locale di caratteri, indipendente dalla quota dell'account DeepL e dalle date di fatturazione.", "type": "integer" }, "requests_per_minute": { "type": "integer" }, "tier": { "enum": [ "free", "pro" ], "type": "string" }, "version": { "type": "string" } }, "required": [ "enabled", "tier", "key_configured", "monthly_limit", "requests_per_minute", "languages", "checked_at", "version", "local_usage" ], "type": "object" }, "TranslationSettingsInput": { "additionalProperties": false, "properties": { "api_key": { "description": "Memorizzata in forma cifrata. Un valore vuoto conserva la chiave salvata salvo che clear_key sia true. La modifica della chiave/del livello richiede un'altra verifica della connessione riuscita.", "maxLength": 1000, "type": "string", "writeOnly": true }, "clear_key": { "type": "boolean" }, "enabled": { "type": "boolean" }, "expected_version": { "type": "string" }, "monthly_limit": { "maximum": 1000000000, "minimum": 1, "type": "integer" }, "requests_per_minute": { "maximum": 60, "minimum": 1, "type": "integer" }, "tier": { "enum": [ "free", "pro" ], "type": "string" } }, "required": [ "enabled", "tier", "monthly_limit", "requests_per_minute", "expected_version" ], "type": "object" }, "TranslationUsage": { "additionalProperties": false, "properties": { "characters": { "description": "Caratteri fatturati con successo più prenotazioni prudenziali per le richieste con risultati sconosciuti. I risultati recuperati dalla cache non aumentano l'utilizzo.", "type": "integer" }, "month": { "description": "Mese solare UTC YYYY-MM.", "type": "string" } }, "required": [ "month", "characters" ], "type": "object" }, "Trial": { "additionalProperties": false, "properties": { "base_url": { "type": "string" }, "duration_days": { "const": 7, "type": "integer" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "isolated": { "type": "boolean" }, "key": { "type": "string", "writeOnly": true }, "license_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "trusted_keys": { "items": { "$ref": "#/components/schemas/SigningKey" }, "type": "array" } }, "required": [ "product_id", "license_id", "key", "trusted_keys" ], "type": "object" }, "UpgradeList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/PlanUpgrade" }, "type": "array" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "UpgradePart": { "additionalProperties": false, "description": "Calcolo di upgrade congelato per un singolo periodo prepagato corrente o futuro. change.amount_cents è la differenza di questo periodo; soltanto il preventivo principale addebita la somma complessiva.", "properties": { "change": { "$ref": "#/components/schemas/PlanUpgrade", "description": "Modifica del prezzo e dei diritti per questa parte dell'upgrade." }, "ends_at": { "description": "Timestamp di fine del pacchetto o del ciclo, UTC; può essere null prima dell'attivazione.", "format": "date-time", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "source": { "description": "Origine del diritto, ad esempio purchase o gift.", "enum": [ "purchase", "gift", "auto_renewal" ], "type": "string" }, "starts_at": { "description": "Timestamp di inizio del pacchetto o del ciclo, UTC.", "format": "date-time", "type": "string" } }, "required": [ "id", "source", "starts_at", "ends_at", "change" ], "type": "object" }, "UpgradeQuoteInput": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "price_version": { "type": "string" }, "request_id": { "maxLength": 80, "type": "string" } }, "required": [ "plan", "currency", "price_version", "request_id" ], "type": "object" }, "Usage": { "additionalProperties": false, "properties": { "active_devices": { "description": "Per il mese UTC corrente: occupazione corrente dei prodotti/dispositivi registrati, indipendente dalla cronologia mensile degli utilizzi dei dispositivi. Le registrazioni ordinarie continuano a essere conteggiate offline fino al rilascio. Le sessioni flottanti vengono conteggiate soltanto finché i relativi lease sono validi e vengono deduplicate in base all'hardware, ripiegando sull'identità del dispositivo. Il rilascio o la scadenza dell'ultima sessione flottante restituisce capacità; le registrazioni valide proseguono oltre i confini dei mesi della quota. Le registrazioni isolate delle prove SDK sono escluse. Per un altro mese UTC: cronologia degli utilizzi distinti dei dispositivi registrata in quel mese.", "type": "integer" }, "api_calls": { "description": "Chiamate activate, validate, heartbeat e deactivate riuscite nel mese UTC e nell'ambiente di pagamento selezionati. Sono esclusi gli errori, le ripetizioni idempotenti valide, i controlli locali e il consumo delle funzionalità software. Per i confronti con la quota del pacchetto acquistato usare purchased.api_calls, che segue il mese della quota del pacchetto.", "type": "integer" }, "api_period": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeAPIPeriod", "description": "Istantanea della quota API predefinita per questo mese UTC; può essere null quando disabilitata." }, { "description": "Istantanea della quota API predefinita per questo mese UTC; può essere null quando disabilitata.", "type": "null" } ], "description": "Quota API predefinita del mese UTC; null se non disponibile. Con un pacchetto acquistato, usare purchased.api_calls e purchased.included_api_calls per il mese della quota corrente." }, "billable_devices": { "description": "Senza acquisti attivi nel mese UTC corrente, occupazione corrente dei dispositivi nella quota predefinita. Per i mesi conclusi o la copertura prepagata, picco di fatturazione salvato del periodo predefinito. Le stime usano almeno il picco registrato; il rilascio di un dispositivo non rimborsa gli addebiti già sostenuti.", "type": "integer" }, "estimated_total_cents": { "description": "Addebito mensile stimato dei dispositivi per il piano predefinito, in centesimi dell'unità valutaria.", "type": "integer" }, "estimated_total_micros": { "description": "Addebito mensile stimato dei dispositivi per il piano predefinito, in milionesimi; non è la somma di tutti gli addebiti dei pacchetti.", "type": "integer" }, "month": { "description": "Mese UTC YYYY-MM; i valori di query omessi usano il mese corrente. Le attività di fatturazione richiedono un mese concluso.", "type": "string" }, "operations": { "description": "Conteggi delle chiamate a consumo riuscite raggruppati per activate, validate, heartbeat e deactivate.", "items": { "additionalProperties": false, "properties": { "count": { "description": "Conteggio nel gruppo corrente oppure numero di record elaborati da un batch.", "type": "integer" }, "operation": { "description": "Nome dell'operazione; i batch supportano create/renew/revoke/apply_policy e le richieste offline activate/deactivate.", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "overage_devices": { "description": "Dispositivi che superano la quota inclusa.", "type": "integer" }, "period": { "anyOf": [ { "$ref": "#/components/schemas/Period", "description": "Istantanea di fatturazione mensile UTC predefinita; le regole di misurazione usano month/day/lifetime e le righe di utilizzo usano la chiave concreta del periodo." }, { "description": "Istantanea di fatturazione mensile UTC predefinita; le regole di misurazione usano month/day/lifetime e le righe di utilizzo usano la chiave concreta del periodo.", "type": "null" } ], "description": "Quota di fatturazione UTC predefinita/storica congelata. Null quando non esiste tale periodo e l'offerta predefinita è disabilitata; un acquisto attivo rimane utilizzabile." }, "products": { "description": "Conteggio dei prodotti nel riepilogo; gruppi di utilizzo dei dispositivi per prodotto nelle risposte sull'utilizzo.", "items": { "additionalProperties": false, "properties": { "active_devices": { "description": "Occupazione corrente per prodotto nel mese UTC corrente; utilizzo storico dei dispositivi distinti per un mese UTC passato.", "type": "integer" }, "product_id": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "purchased": { "anyOf": [ { "$ref": "#/components/schemas/PlanPurchase", "description": "Pacchetto attivo corrente con mese mobile oppure null." }, { "description": "Pacchetto attivo corrente con mese mobile oppure null.", "type": "null" } ], "description": "Pacchetto attivo nell'ambiente di pagamento corrente, restituito soltanto per il mese UTC corrente. La quota dispositivi principale deve usare purchased.included_devices, non period.included_devices." }, "purchased_active_devices": { "description": "Quando purchased è presente: occupazione corrente dei prodotti/dispositivi registrati, indipendente dalla cronologia mensile degli utilizzi dei dispositivi. Le registrazioni ordinarie continuano a essere conteggiate offline fino al rilascio. Le sessioni flottanti vengono conteggiate soltanto finché i relativi lease sono validi e vengono deduplicate in base all'hardware, ripiegando sull'identità del dispositivo. Il rilascio o la scadenza dell'ultima sessione flottante restituisce capacità; le registrazioni valide proseguono oltre i confini dei mesi della quota. Le registrazioni isolate delle prove SDK sono escluse.", "type": "integer" }, "sandbox": { "description": "Ambiente di test", "type": "boolean" }, "timezone": { "description": "Fuso orario di aggregazione dell'utilizzo, UTC.", "type": "string" }, "warning": { "description": "normal, near_quota o quota_reached per la quota predefinita dei dispositivi.", "type": "string" } }, "required": [], "type": "object" }, "UsageDevice": { "additionalProperties": false, "properties": { "device_id": { "description": "Impronta del dispositivo specifica del prodotto, normalmente di 64 caratteri esadecimali minuscoli, derivata dall'SDK.", "type": "string" }, "first_seen_at": { "description": "Timestamp della prima attività del dispositivo in questo mese UTC.", "format": "date-time", "type": "string" }, "last_seen_at": { "description": "Timestamp dell'ultima attività del dispositivo osservata dal server, UTC.", "format": "date-time", "type": "string" }, "month": { "description": "Mese UTC YYYY-MM; i valori di query omessi usano il mese corrente. Le attività di fatturazione richiedono un mese concluso.", "type": "string" }, "product_id": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "UsageDeviceList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/UsageDevice" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "Verified": { "additionalProperties": false, "properties": { "verified": { "type": "boolean" } }, "required": [ "verified" ], "type": "object" }, "VersionedActivationReleaseInput": { "additionalProperties": false, "properties": { "expected_generation": { "description": "Generazione dell'associazione visualizzata nell'elenco corrente dei dispositivi. Obbligatoria per le associazioni degli account Launch; le versioni obsolete non rilasciano mai un'associazione più recente.", "minimum": 1, "type": "integer" }, "operation_id": { "description": "UUID stabile dell'operazione per il recupero tramite tentativi successivi. Obbligatorio per le associazioni degli account Launch.", "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "WaffoCheck": { "additionalProperties": false, "properties": { "connected": { "description": "Abilitato", "type": "boolean" }, "mode": { "description": "Ambiente di pagamento. I record sandbox e live sono isolati.", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "connected", "mode" ], "type": "object" }, "WaffoOrder": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Prezzo completo del servizio congelato nell'unità monetaria minima; nessuna ricarica del portafoglio o pagamento misto.", "type": "integer" }, "applied_at": { "anyOf": [ { "description": "Scadenza UTC della finestra originale di creazione del checkout.", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Ora UTC in cui il pagamento verificato ha attivato il servizio o accreditato una ricarica del portafoglio. purchase_id e upgrade_id null identificano una ricarica." }, "checkout_expires_at": { "description": "Scadenza UTC della finestra originale di creazione del checkout.", "format": "date-time", "type": "string" }, "created_at": { "description": "Scadenza UTC della finestra originale di creazione del checkout.", "format": "date-time", "type": "string" }, "currency": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" }, "mode": { "description": "Ambiente di pagamento. I record sandbox e live sono isolati.", "enum": [ "sandbox", "live" ], "type": "string" }, "paid_at": { "anyOf": [ { "description": "Scadenza UTC della finestra originale di creazione del checkout.", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Ora UTC in cui il backend ha verificato una transazione Waffo completata." }, "provider_order_id": { "anyOf": [ { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, { "type": "null" } ], "description": "Identificativo ORD_ originale recuperato da una risposta API verificata." }, "purchase_id": { "anyOf": [ { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Acquisto di servizio o rinnovo esistente in sospeso; mutuamente esclusivo con upgrade_id." }, "refunded_cents": { "description": "Prezzo completo del servizio congelato nell'unità monetaria minima; nessuna ricarica del portafoglio o pagamento misto.", "type": "integer" }, "request_id": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "status": { "description": "Ciclo di vita del pagamento, incluso paid_unapplied quando i fondi incassati richiedono revisione e rimborso da parte dell'operatore.", "enum": [ "creating", "created", "completed", "paid_unapplied", "partially_refunded", "refunded" ], "type": "string" }, "upgrade_id": { "anyOf": [ { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Preventivo di upgrade esistente in sospeso; mutuamente esclusivo con purchase_id." } }, "required": [ "id", "request_id", "mode", "provider_order_id", "purchase_id", "upgrade_id", "currency", "amount_cents", "refunded_cents", "status", "checkout_expires_at", "paid_at", "applied_at", "created_at" ], "type": "object" }, "WaffoOrderInput": { "additionalProperties": false, "description": "Paga un singolo acquisto/upgrade congelato oppure crea una ricarica del portafoglio con amount e currency e senza ID di servizio. Un request_id stabile restituisce il pagamento originale; la modifica dell'intenzione, dell'importo o della valuta viene rifiutata. Solo i pagamenti completati e verificati indipendentemente accreditano un portafoglio o attivano il servizio. I ritorni delle ricariche portano al portafoglio. I tentativi successivi riutilizzano la chiave di idempotenza originale del fornitore soltanto entro la finestra originale di creazione del checkout.", "oneOf": [ { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "format": "uuid", "type": "string" }, "upgrade_id": { "type": "null" } }, "required": [ "purchase_id" ] }, { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "format": "uuid", "type": "string" } }, "required": [ "upgrade_id" ] }, { "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "type": "null" } }, "required": [ "amount", "currency" ] } ], "properties": { "amount": { "description": "Obbligatorio soltanto per una ricarica del portafoglio. Importo decimale visualizzato entro i limiti configurati. Gli ordini di servizio rifiutano gli importi forniti dal client.", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "type": "string" }, "currency": { "description": "Obbligatorio soltanto per una ricarica del portafoglio e deve essere abilitato per questo fornitore.", "type": "string" }, "overage_accepted": { "description": "Autorizzazione esplicita separata degli sforamenti a pagamento visualizzati.", "type": "boolean" }, "policy_version": { "description": "Versione immutabile della politica attualmente pubblicata. Obbligatoria per le azioni protette dal consenso dopo che l'operatore ha pubblicato una politica, in entrambi gli ambienti di pagamento.", "type": "string" }, "purchase_id": { "anyOf": [ { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Acquisto di servizio o rinnovo esistente in sospeso; mutuamente esclusivo con upgrade_id." }, "request_id": { "description": "Chiave di richiesta stabile generata dal chiamante. Le ripetizioni restituiscono il checkout originale.", "maxLength": 80, "type": "string" }, "terms_accepted": { "description": "Accettazione esplicita, non preselezionata per impostazione predefinita.", "type": "boolean" }, "upgrade_id": { "anyOf": [ { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Preventivo di upgrade esistente in sospeso; mutuamente esclusivo con purchase_id." } }, "required": [ "request_id" ], "type": "object" }, "WaffoOrderList": { "additionalProperties": false, "properties": { "items": { "description": "Elementi", "items": { "$ref": "#/components/schemas/WaffoOrder" }, "type": "array" }, "total": { "description": "Prezzo completo del servizio congelato nell'unità monetaria minima; nessuna ricarica del portafoglio o pagamento misto.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "WaffoOrderResult": { "additionalProperties": false, "properties": { "approval_url": { "description": "URL di checkout autenticato di breve durata oppure vuoto dopo il pagamento, la scadenza o la disabilitazione del canale. Non registrarlo mai nei log né nella cache.", "type": "string" }, "order": { "$ref": "#/components/schemas/WaffoOrder", "description": "Ordine" }, "return_url": { "description": "URL del pannello del portafoglio per una ricarica, URL di riconciliazione dei prezzi per un pagamento di servizio. Un URL di ritorno da solo non dimostra mai il pagamento.", "format": "uri", "type": "string" } }, "required": [ "order", "approval_url", "return_url" ], "type": "object" }, "WaffoSettings": { "additionalProperties": false, "properties": { "currencies": { "description": "Valute", "items": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "type": "array" }, "enabled": { "description": "Abilitato", "type": "boolean" }, "maximum_cents": { "description": "Ricarica massima del portafoglio in unità monetarie minime; valore predefinito 100000 e non deve essere inferiore a minimum_cents.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "merchant_id": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "minimum_cents": { "description": "Ricarica minima del portafoglio in unità monetarie minime; valore predefinito 100.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "Ambiente di pagamento. I record sandbox e live sono isolati.", "enum": [ "sandbox", "live" ], "type": "string" }, "private_key_configured": { "description": "Abilitato", "type": "boolean" }, "product_id": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "store_id": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "version": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "webhook_public_key": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "webhook_url": { "description": "URL webhook", "format": "uri", "type": "string" } }, "required": [ "enabled", "mode", "merchant_id", "store_id", "product_id", "currencies", "private_key_configured", "webhook_public_key", "version", "webhook_url" ], "type": "object" }, "WaffoSettingsInput": { "additionalProperties": false, "properties": { "clear_private_key": { "description": "Abilitato", "type": "boolean" }, "currencies": { "description": "Valute", "items": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "type": "array" }, "enabled": { "description": "Abilitato", "type": "boolean" }, "expected_version": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "maximum_cents": { "description": "Ricarica massima del portafoglio in unità monetarie minime; valore predefinito 100000 e non deve essere inferiore a minimum_cents.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "merchant_id": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "minimum_cents": { "description": "Ricarica minima del portafoglio in unità monetarie minime; valore predefinito 100.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "Ambiente di pagamento. I record sandbox e live sono isolati.", "enum": [ "sandbox", "live" ], "type": "string" }, "private_key": { "description": "Chiave privata di firma RSA. Cifrata a riposo; un valore vuoto conserva la chiave salvata.", "maxLength": 8192, "type": "string", "writeOnly": true }, "product_id": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "store_id": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" }, "webhook_public_key": { "description": "Sostituzione facoltativa della chiave pubblica ufficiale del webhook. Un valore vuoto usa la chiave dell'SDK per l'ambiente selezionato.", "maxLength": 8192, "type": "string" } }, "required": [ "enabled", "mode", "merchant_id", "store_id", "product_id", "currencies", "expected_version" ], "type": "object" }, "WaffoWebhookEvent": { "description": "Evento Waffo originale autenticato con X-Waffo-Signature, la chiave pubblica dell'ambiente selezionato, store e mode. I pagamenti/rimborsi vengono verificati indipendentemente tramite l'API.", "type": "object" }, "Wallet": { "additionalProperties": false, "properties": { "balance_cents": { "description": "Saldo del portafoglio oppure saldo successivo al movimento, in centesimi.", "type": "integer" }, "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [], "type": "object" }, "WalletEntry": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Importo in centesimi; le registrazioni contabili possono essere accrediti positivi o addebiti negativi.", "type": "integer" }, "balance_cents": { "description": "Saldo del portafoglio oppure saldo successivo al movimento, in centesimi.", "type": "integer" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "currency": { "description": "Codice valuta di tre lettere maiuscole, ad esempio USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "kind": { "description": "plan_upgrade registra un upgrade pagato. paypal_refund_reserve blocca fondi disponibili del portafoglio; paypal_refund_release rimuove tale blocco; paypal_refund registra il rimborso in denaro confermato. I movimenti di prenotazione/rilascio non sono pagamenti in denaro e si compensano al completamento del regolamento.", "type": "string" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" }, "reference": { "description": "Riferimento applicativo correlato usato per il tracciamento.", "type": "string" } }, "required": [], "type": "object" }, "WalletEntryList": { "additionalProperties": false, "properties": { "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/WalletEntry" }, "type": "array" }, "limit": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "type": "integer" }, "offset": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "type": "integer" }, "total": { "description": "Numero totale di record corrispondenti, non la lunghezza della pagina corrente.", "type": "integer" } }, "required": [], "type": "object" }, "WalletRefundRequest": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 1, "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "customer_email": { "description": "Solo elenco amministrativo.", "type": "string" }, "decision": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "format": "uuid", "type": "string" }, "reason": { "type": "string" }, "refund_id": { "format": "uuid", "type": [ "string", "null" ] }, "refund_status": { "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "review_status": { "enum": [ "pending", "approved", "declined", "cancelled" ], "type": "string" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending_review", "refund_pending", "refunded", "refund_failed", "declined", "cancelled" ], "type": "string" }, "tenant_name": { "description": "Solo elenco amministrativo.", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "order_id", "mode", "currency", "amount_cents", "reason", "status", "review_status" ], "type": "object" }, "WalletRefundRequestInput": { "additionalProperties": false, "properties": { "amount": { "description": "Importo positivo, limitato sia dal valore dell'ordine non rimborsato sia dal credito corrente non speso del portafoglio.", "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "reason": { "maxLength": 255, "minLength": 1, "type": "string" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "amount", "reason", "request_id", "mode" ], "type": "object" }, "WalletRefundRequestList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/WalletRefundRequest" }, "type": "array" }, "limit": { "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "items", "total", "mode" ], "type": "object" }, "WalletRefundReview": { "additionalProperties": false, "properties": { "approve": { "type": "boolean" }, "decision": { "maxLength": 1000, "minLength": 1, "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" } }, "required": [ "approve", "decision" ], "type": "object" }, "WalletResult": { "additionalProperties": false, "properties": { "currencies": { "description": "Codici valuta consentiti in questo ambiente.", "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "items": { "description": "Record restituiti; consultare items[] per i campi degli elementi. Alcune raccolte vuote possono essere null; consultare il tipo.", "items": { "$ref": "#/components/schemas/Wallet" }, "type": "array" }, "maximum_cents": { "description": "Ricarica massima per il canale di ricarica del portafoglio abilitato, in unità monetarie minime.", "type": "integer" }, "minimum_cents": { "description": "Ricarica minima per il canale di ricarica del portafoglio abilitato, in unità monetarie minime.", "type": "integer" }, "mode": { "description": "Durata della licenza: perpetual, timed o trial; gli oggetti di fatturazione usano la modalità di pagamento sandbox o live.", "enum": [ "sandbox", "live" ], "type": "string" }, "payment_channels": { "description": "Configurazione dei canali di pagamento disponibili. Mostrare soltanto i canali abilitati che corrispondono all'ambiente di fatturazione attivo e alla valuta dell'acquisto.", "items": { "$ref": "#/components/schemas/PaymentChannel" }, "type": "array" }, "paypal_enabled": { "description": "Indica se PayPal è abilitato in questo ambiente di pagamento.", "type": "boolean" } }, "required": [], "type": "object" }, "WebhookAttempt": { "additionalProperties": false, "properties": { "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "delivery_id": { "description": "UUID dell'attività di consegna per questo tentativo.", "format": "uuid", "type": "string" }, "duration_ms": { "description": "Durata della consegna in millisecondi.", "type": "integer" }, "error": { "description": "Oggetto di errore o categoria di errore di consegna; consultare i campi subordinati o il tipo corrente.", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "number": { "description": "Numero progressivo cumulativo del tentativo.", "type": "integer" }, "status_code": { "description": "Stato HTTP di questo tentativo; può essere 0 in caso di errore di trasporto.", "type": "integer" } }, "required": [ "id", "delivery_id", "number", "status_code", "error", "duration_ms", "created_at" ], "type": "object" }, "WebhookDelivery": { "additionalProperties": false, "properties": { "attempts": { "description": "Numero cumulativo di tentativi dell'attività.", "type": "integer" }, "available_at": { "description": "Primo orario UTC in cui l'attività può essere eseguita.", "format": "date-time", "type": "string" }, "created_at": { "description": "Ora di creazione in UTC; le richieste offline usano secondi Unix.", "format": "date-time", "type": "string" }, "delivered_at": { "anyOf": [ { "description": "Timestamp di consegna riuscita oppure null.", "format": "date-time", "type": "string" }, { "description": "Timestamp di consegna riuscita oppure null.", "type": "null" } ], "description": "Timestamp di consegna riuscita oppure null." }, "endpoint_id": { "description": "UUID dell'endpoint webhook.", "format": "uuid", "type": "string" }, "event_id": { "description": "UUID dell'evento originale; usarlo per la deduplicazione del destinatario.", "format": "uuid", "type": "string" }, "id": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" }, "last_error": { "description": "Categoria dell'errore più recente; può essere vuota.", "type": "string" }, "last_status": { "description": "Stato della risposta HTTP più recente; può essere 0 se non è arrivata alcuna risposta.", "type": "integer" }, "status": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "type": "string" } }, "required": [ "id", "endpoint_id", "event_id", "status", "attempts", "available_at", "last_status", "last_error", "delivered_at", "created_at" ], "type": "object" }, "WebhookEvent": { "description": "Evento PayPal firmato esatto, verificato con l'API PayPal", "type": "object" }, "WebhookReceived": { "additionalProperties": false, "properties": { "ignored": { "type": "boolean" }, "received": { "type": "boolean" } }, "required": [], "type": "object" } }, "securitySchemes": { "closureExport": { "description": "Credenziale di download limitata di 15 minuti, mai una sessione del pannello. In produzione si usa __Host-licentivo_closure_export; sempre limitata dalla scadenza originale della chiusura.", "in": "cookie", "name": "licentivo_closure_export", "type": "apiKey" }, "customerSession": { "description": "In produzione si usa __Host-licenova_customer; l'identità dell'acquirente è indipendente dalla sessione del fornitore.", "in": "cookie", "name": "licenova_customer", "type": "apiKey" }, "managementKey": { "bearerFormat": "lv_api_...", "scheme": "bearer", "type": "http" }, "session": { "description": "In produzione si usa __Host-licenova_session", "in": "cookie", "name": "licenova_session", "type": "apiKey" } } }, "info": { "description": "API di gestione e concessione delle licenze Licentivo. Supporta autorizzazioni di esecuzione firmate, licenze vincolate a un dispositivo e flottanti, quote dei dispositivi attualmente attivati, utilizzo mensile delle API, funzionalità software a consumo, sessioni degli account Launch, pacchetti prepagati, regali, rinnovo automatico tramite portafoglio e upgrade dell'intera copertura. PayPal, Paddle e Waffo supportano pagamenti verificati e rimborsi tramite il metodo di pagamento originale. Sono incluse politiche per i clienti, annullamenti limitati all'ambito dell'approvazione, assistenza, compensazioni, esportazione dei dati e chiusura logica degli account. Gli ambienti di pagamento e le valute sono isolati; le credenziali private sono cifrate e non vengono mai restituite.", "title": "API Licentivo", "version": "0.12.0", "x-document-language": "it" }, "openapi": "3.1.0", "paths": { "/api/v1/account/closure-export.zip": { "get": { "description": "La credenziale e la scadenza originale della chiusura vengono ricontrollate per ogni richiesta e dopo la generazione. Il ripristino di un backup non può riavviare la finestra.", "operationId": "get__api_v1_account_closure_export_zip", "parameters": [], "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "closureExport": [] } ], "summary": "Scarica durante la finestra di 30 giorni dalla chiusura" } }, "/api/v1/account/closure-export/session": { "post": { "description": "Richiede l'email originale verificata e la password, nonché una chiusura confermata ancora entro il periodo esatto di 30 giorni. Il cookie di 15 minuti è limitato dalla scadenza originale, soggetto a limiti di frequenza e non può autorizzare il normale accesso alle API/al pannello.", "operationId": "post__api_v1_account_closure_export_session", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosureExportLogin" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ClosureExportCredential" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [], "summary": "Verifica un account chiuso per un'esportazione limitata" } }, "/api/v1/account/data-export": { "get": { "description": "I download del proprietario includono i CSV dei dati applicativi dello spazio di lavoro. L'archivio personale di un membro contiene il proprio profilo, i post e le richieste. Sono esclusi i segreti/gli hash delle credenziali e le chiavi private di firma.", "operationId": "get__api_v1_account_data_export", "parameters": [], "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Scarica i propri dati personali e quelli autorizzati", "x-required-role": "session" } }, "/api/v1/account/deletions": { "get": { "description": "", "operationId": "get__api_v1_account_deletions", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AccountClosureList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge le proprie richieste di chiusura logica", "x-required-role": "session" }, "post": { "description": "Il proprietario che richiede la chiusura deve selezionare workspace; un membro può chiudere soltanto il proprio account. La conferma revoca le sessioni/le chiavi API ma conserva i dati. L'esportazione è consentita per 30 giorni dopo la conferma.", "operationId": "post__api_v1_account_deletions", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountClosureInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AccountClosure" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Richiede la chiusura logica di un account o spazio di lavoro", "x-required-role": "session" } }, "/api/v1/account/deletions/{id}/cancel": { "post": { "description": "", "operationId": "post__api_v1_account_deletions__id__cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Ritira una chiusura non confermata", "x-required-role": "session" } }, "/api/v1/account/legal-acceptances": { "get": { "description": "", "operationId": "get__api_v1_account_legal_acceptances", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LegalAcceptanceList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge le proprie ricevute di accettazione legale", "x-required-role": "session" } }, "/api/v1/account/profile": { "patch": { "description": "Richiede la password corrente. Il nuovo indirizzo email di accesso riceve un link di verifica monouso valido per 30 minuti. L'indirizzo di accesso verificato corrente e l'accesso rimangono invariati fino alla conferma.", "operationId": "patch__api_v1_account_profile", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCorrection" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Corregge il proprio nome o richiede la modifica dell'email di accesso", "x-required-role": "session" } }, "/api/v1/activate": { "post": { "description": "Autenticazione tramite product_id + license_key + device_id. Nessun cookie/CSRF/chiave del fornitore. activation_id è obbligatorio tranne che per activate. Ogni richiesta riuscita consuma una chiamata API; le ripetizioni idempotenti e gli errori non consumano chiamate. Gli sforamenti addebitano il portafoglio in modo atomico oppure restituiscono API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT. La quota dei dispositivi dello spazio di lavoro segue le attivazioni correnti. Il rilascio restituisce capacità; anche la scadenza di un lease flottante restituisce capacità, mentre una registrazione ordinaria offline continua a essere conteggiata. Gli sforamenti dei dispositivi vengono addebitati soltanto quando il picco di fatturazione del mese della quota supera la capacità già pagata; il rilascio non rimborsa i costi già sostenuti. L'utilizzo delle API è separato.", "operationId": "post_api_v1_activate", "parameters": [ { "description": "Generare una nuova chiave per ogni operazione; i tentativi successivi conservano la stessa chiave e lo stesso corpo. Massimo 80 caratteri, senza spazi bianchi. Facoltativa per la convalida e l'heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Attivazione in fase di esecuzione" } }, "/api/v1/activations": { "get": { "operationId": "get_api_v1_activations", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "license_id", "schema": { "description": "UUID della licenza, distinto dal segreto lv_lic_.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "product_id", "schema": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "status", "schema": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "active", "released" ], "type": "string" } }, { "in": "query", "name": "q", "schema": { "description": "Testo di ricerca; i campi interessati e la lunghezza massima dipendono dall'operazione.", "maxLength": 120, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "generation": 1, "id": "44444444-4444-4444-8444-444444444444", "last_seen_at": "2026-10-18T00:00:00Z", "license_id": "33333333-3333-4333-8333-333333333333", "product_id": "11111111-1111-4111-8111-111111111111", "released_at": null, "status": "active", "virtual_machine": false } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ActivationList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca le attivazioni", "x-management-reference": { "group": "devices" }, "x-required-scope": "read" } }, "/api/v1/activations/{id}/release": { "post": { "operationId": "post_api_v1_activations_by_id_release", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "expected_generation": 1, "operation_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/VersionedActivationReleaseInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "released" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Rilascia un'attivazione", "x-management-reference": { "group": "devices" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/api-keys": { "get": { "operationId": "get_api_v1_api-keys", "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "allow_http": false, "created_at": "2026-10-18T00:00:00Z", "expires_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "name": "Report app", "prefix": "lv_api_AAAAAAA", "revoked": false, "scope": "read" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Elenca le chiavi API", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" }, "post": { "operationId": "post_api_v1_api-keys", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "Obbligatorio per le scritture autenticate tramite cookie; ottenere data.csrf_token da GET /api/v1/auth/csrf e conservare i cookie.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "allow_http": false, "expires_days": 90, "name": "Order system", "scope": "write" }, "schema": { "$ref": "#/components/schemas/KeyCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "expires_at": "2027-01-16T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "prefix": "lv_api_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeySecret", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Crea la chiave API", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" } }, "/api/v1/api-keys/{id}": { "delete": { "operationId": "delete_api_v1_api-keys_by_id", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "Obbligatorio per le scritture autenticate tramite cookie; ottenere data.csrf_token da GET /api/v1/auth/csrf e conservare i cookie.", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Revoca la chiave API", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" }, "patch": { "description": "Richiede una sessione Owner e un token CSRF. Aggiorna soltanto questa chiave attiva; la rotazione conserva l'impostazione. Non modifica le connessioni Launch o le autorizzazioni di esecuzione esistenti. Questa impostazione non abilita HTTP sull'API Licentivo.", "operationId": "patch_api_v1_api-keys_by_id", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "Obbligatorio per le scritture autenticate tramite cookie; ottenere data.csrf_token da GET /api/v1/auth/csrf e conservare i cookie.", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "allow_http": true }, "schema": { "$ref": "#/components/schemas/KeyUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "allow_http": false, "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyUpdated", "description": "Response data for the completed operation." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Aggiorna l'accesso HTTP ai siti", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" } }, "/api/v1/api-keys/{id}/rotate": { "post": { "operationId": "post_api_v1_api-keys_by_id_rotate", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "Obbligatorio per le scritture autenticate tramite cookie; ottenere data.csrf_token da GET /api/v1/auth/csrf e conservare i cookie.", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", "prefix": "lv_api_BBBBBBB" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyRotated", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Ruota la chiave API", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" } }, "/api/v1/audit-logs": { "get": { "operationId": "get_api_v1_audit-logs", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "action": "license.create", "actor_id": "33333333-3333-4333-8333-333333333333", "actor_kind": "api_key", "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "request_id": "55555555-5555-4555-8555-555555555555", "resource_id": "" } ], "limit": 25, "offset": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AuditList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca i log di controllo", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/auth/accept-invitation": { "post": { "operationId": "post_api_v1_auth_accept-invitation", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenPassword" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PasswordSet" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Accetta l'invito" } }, "/api/v1/auth/change-password": { "post": { "operationId": "post_api_v1_auth_change-password", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePassword" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PasswordSet" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Revoca tutte le credenziali dell'account e imposta la password" } }, "/api/v1/auth/confirm-email-change": { "post": { "description": "Verifica la richiesta di verifica cifrata e monouso. Solo una conferma riuscita modifica l'email di accesso, la verifica e revoca le sessioni, le chiavi API e i link di autenticazione esistenti. Le richieste di verifica scadute, sostituite o invalidate da una modifica della password non possono cambiare l'account.", "operationId": "post__api_v1_auth_confirm_email_change", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailChangeConfirmation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [], "summary": "Conferma una nuova email di accesso" } }, "/api/v1/auth/csrf": { "get": { "operationId": "get_api_v1_auth_csrf", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CSRF" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Emette un token CSRF associato alla sessione" } }, "/api/v1/auth/forgot-password": { "post": { "operationId": "post_api_v1_auth_forgot-password", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Password dimenticata" } }, "/api/v1/auth/login": { "post": { "operationId": "post_api_v1_auth_login", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Login" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CSRF" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Accesso" } }, "/api/v1/auth/logout": { "post": { "operationId": "post_api_v1_auth_logout", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoggedOut" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Revoca la sessione corrente" } }, "/api/v1/auth/me": { "get": { "operationId": "get_api_v1_auth_me", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Me" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Account corrente autenticato tramite cookie" } }, "/api/v1/auth/register": { "post": { "description": "I termini pubblicati richiedono policy_version e l'accettazione esplicita in entrambi gli ambienti di pagamento. Gli sforamenti del servizio a pagamento richiedono inoltre overage_accepted. Prima della prima pubblicazione delle politiche, il consenso alle bozze non viene registrato e ogni operazione continua a seguire le normali verifiche di registrazione, prezzo e pagamento.", "operationId": "post_api_v1_auth_register", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Register" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Registrazione" } }, "/api/v1/auth/resend-verification": { "post": { "operationId": "post_api_v1_auth_resend-verification", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Reinvia l'email di verifica" } }, "/api/v1/auth/reset-password": { "post": { "operationId": "post_api_v1_auth_reset-password", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenPassword" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PasswordSet" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Reimposta la password" } }, "/api/v1/auth/verify-email": { "post": { "operationId": "post_api_v1_auth_verify-email", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Verified" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Verifica dell'email" } }, "/api/v1/billing/auto-renewal": { "get": { "description": "Solo sessioni. PATCH richiede il ruolo Owner dello spazio di lavoro. Disabilitato per impostazione predefinita. L'abilitazione richiede un saldo sufficiente, nella modalità e nella valuta correnti, per un rinnovo, oltre alla revisione dell'ultimo piano pagato, della durata offerta e della versione del prezzo. Alla scadenza vengono addebitati soltanto i fondi del portafoglio, mai PayPal o una carta. Un worker eseguito ogni minuto e le modifiche in fase di esecuzione elaborano i rinnovi dovuti sotto un blocco del tenant. I tentativi ripetuti addebitano una sola volta. Se i fondi sono insufficienti, si attende una ricarica; le modifiche al prezzo, al piano o alla disponibilità sospendono gli addebiti in attesa di un nuovo consenso. La disabilitazione annulla gli addebiti automatici futuri, senza annullare la copertura già pagata.", "operationId": "get_api_v1_billing_auto_renewal", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "next_renewal_at": null, "setting": { "amount_cents": 0, "currency": "USD", "enabled": true, "mode": "sandbox", "plan": "starter", "plan_name": "Starter", "policy_version": "", "price_version": "example-v1", "status": "disabled", "term_months": 1, "updated_at": "2026-10-18T00:00:00Z", "version": "" } }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AutoRenewalResult", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Legge le impostazioni del rinnovo automatico", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "patch": { "description": "Solo sessioni. PATCH richiede il ruolo Owner dello spazio di lavoro. Disabilitato per impostazione predefinita. L'abilitazione richiede un saldo sufficiente, nella modalità e nella valuta correnti, per un rinnovo, oltre alla revisione dell'ultimo piano pagato, della durata offerta e della versione del prezzo. Alla scadenza vengono addebitati soltanto i fondi del portafoglio, mai PayPal o una carta. Un worker eseguito ogni minuto e le modifiche in fase di esecuzione elaborano i rinnovi dovuti sotto un blocco del tenant. I tentativi ripetuti addebitano una sola volta. Se i fondi sono insufficienti, si attende una ricarica; le modifiche al prezzo, al piano o alla disponibilità sospendono gli addebiti in attesa di un nuovo consenso. La disabilitazione annulla gli addebiti automatici futuri, senza annullare la copertura già pagata. I termini pubblicati richiedono policy_version e l'accettazione esplicita in entrambi gli ambienti di pagamento. Gli sforamenti del servizio a pagamento richiedono inoltre overage_accepted. Prima della prima pubblicazione delle politiche, il consenso alle bozze non viene registrato e ogni operazione continua a seguire le normali verifiche di registrazione, prezzo e pagamento.", "operationId": "patch_api_v1_billing_auto_renewal", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRenewalInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AutoRenewal" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Abilita o disabilita il rinnovo tramite portafoglio con consenso esplicito" } }, "/api/v1/billing/invoices": { "get": { "operationId": "get_api_v1_billing_invoices", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "month", "schema": { "description": "Mese UTC YYYY-MM; i valori di query omessi usano il mese corrente. Le attività di fatturazione richiedono un mese concluso.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "active_devices": 0, "base_covered": false, "base_micros": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "finalized_at": null, "id": "33333333-3333-4333-8333-333333333333", "included_devices": 0, "month": "2026-09", "overage_devices": 0, "paid_at": null, "payment_mode": "sandbox", "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "refunded_at": null, "status": "draft", "total_cents": 0, "total_micros": 0, "unit_micros": 0, "voided_at": null } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InvoiceList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca le fatture", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/invoices/{id}": { "get": { "operationId": "get_api_v1_billing_invoices_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active_devices": 0, "base_covered": false, "base_micros": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "finalized_at": null, "id": "33333333-3333-4333-8333-333333333333", "included_devices": 0, "month": "2026-09", "overage_devices": 0, "paid_at": null, "payment_mode": "sandbox", "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "refunded_at": null, "status": "draft", "total_cents": 0, "total_micros": 0, "unit_micros": 0, "voided_at": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Invoice", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Legge una fattura", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/invoices/{id}/export.csv": { "get": { "operationId": "get_api_v1_billing_invoices_by_id_export_csv", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "example": "invoice_id,month,currency,status,plan,price_version,active_devices,included_devices,overage_devices,base_micros,unit_micros,total_micros,total_cents\n", "schema": { "type": "string" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Esporta una fattura", "x-csv-columns": [ "invoice_id", "month", "currency", "status", "plan", "price_version", "active_devices", "included_devices", "overage_devices", "base_micros", "unit_micros", "total_micros", "total_cents" ], "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/invoices/{id}/finalize": { "post": { "operationId": "post_api_v1_billing_invoices_by_id_finalize", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "finalized" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Finalizza una fattura", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/invoices/{id}/pay": { "post": { "description": "Prima di un nuovo pagamento è richiesta l'accettazione esplicita della politica corrente. La ripetizione di un pagamento già effettuato conserva la ricevuta originale.", "operationId": "post_api_v1_billing_invoices_by_id_pay", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalConsent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Paga una fattura storica confermata usando il saldo", "x-required-role": "owner" } }, "/api/v1/billing/invoices/{id}/void": { "post": { "operationId": "post_api_v1_billing_invoices_by_id_void", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "void" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Annulla una fattura", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/jobs": { "get": { "operationId": "get_api_v1_billing_jobs", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "attempts": 0, "available_at": "2026-10-18T00:00:00Z", "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "last_error": "", "month": "2026-09", "status": "pending" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingJobList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca le attività di fatturazione", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "post": { "operationId": "post_api_v1_billing_jobs", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "month": "2026-09" }, "schema": { "$ref": "#/components/schemas/MonthInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "attempts": 0, "available_at": "2026-10-18T00:00:00Z", "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "last_error": "", "month": "2026-09", "status": "pending" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingJob", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Accoda un'attività di fatturazione", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/jobs/{id}/retry": { "post": { "operationId": "post_api_v1_billing_jobs_by_id_retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "pending" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Riprova un'attività di fatturazione", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/notification-preferences": { "get": { "description": "Solo sessioni Owner; le chiavi amministrative vengono rifiutate. Per impostazione predefinita, tutti e quattro i tipi sono abilitati e la lingua è zh fino al salvataggio esplicito. Le preferenze appartengono a questo utente e spazio di lavoro. Riutilizza il trasporto delle email di autenticazione, il mittente, la coda persistente cifrata e i tentativi successivi. Sia il permesso della piattaforma sia il consenso del destinatario devono consentire il tipo di messaggio. La consegna verifica nuovamente il consenso corrente e lo stato dell'evento. Le preferenze email non concedono né revocano il consenso agli addebiti sul portafoglio. I messaggi sandbox sono contrassegnati. Non vengono create notifiche per acquisti in sospeso non pagati o per regali.", "operationId": "get__api_v1_billing_notification_preferences", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationPreferencesResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge il consenso email del proprietario corrente", "x-required-role": "owner" }, "patch": { "description": "Aggiornamento parziale per il proprietario della sessione; non può riguardare un altro utente. La lingua impostata controlla i messaggi futuri. Le email di verifica e di sicurezza esistenti rimangono indipendenti. Riutilizza il trasporto delle email di autenticazione, il mittente, la coda persistente cifrata e i tentativi successivi. Sia il permesso della piattaforma sia il consenso del destinatario devono consentire il tipo di messaggio. La consegna verifica nuovamente il consenso corrente e lo stato dell'evento. Le preferenze email non concedono né revocano il consenso agli addebiti sul portafoglio. I messaggi sandbox sono contrassegnati. Non vengono create notifiche per acquisti in sospeso non pagati o per regali.", "operationId": "patch__api_v1_billing_notification_preferences", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingNotificationPreferenceInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationPreference" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Salva il consenso email del proprietario corrente", "x-required-role": "owner" } }, "/api/v1/billing/overage-consent": { "post": { "description": "", "operationId": "post__api_v1_billing_overage_consent", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerOverageConsent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Autorizza esplicitamente gli sforamenti correnti tramite portafoglio", "x-required-role": "owner" } }, "/api/v1/billing/overage-settings": { "get": { "description": "Solo tenant corrente. I membri con accesso in sola lettura possono visualizzarle. Una quota API illimitata non viene mai limitata da una preferenza del cliente sugli sforamenti. Un piano null indica che la quota predefinita non è disponibile.", "operationId": "get__api_v1_billing_overage_settings", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "customer_api_settings_enabled": false, "customer_device_settings_enabled": false, "plan": null, "preference": { "block_api_overage": false, "block_device_overage": false, "mode": "sandbox", "updated_at": "2026-10-18T00:00:00Z", "version": "" } }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OverageSettings", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Legge le preferenze sugli sforamenti", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "patch": { "description": "Solo sessioni Owner. Ogni scelta fornita richiede il permesso amministrativo corrispondente; un campo non autorizzato causa il rifiuto dell'intera richiesta con 403. Limite rigido in fase di esecuzione = limite amministrativo OR preferenza di blocco del cliente quando quel permesso è abilitato. Non cancella utilizzi o addebiti precedenti. Le preferenze sandbox e live sono indipendenti.", "operationId": "patch__api_v1_billing_overage_settings", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverageSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OveragePreference" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Salva preferenze separate sugli sforamenti dei dispositivi e delle API" } }, "/api/v1/billing/paddle/orders": { "get": { "operationId": "get__api_v1_billing_paddle_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderList" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Elenca i pagamenti di servizi e le ricariche del portafoglio Paddle", "x-licentivo-access": "session" }, "post": { "operationId": "post__api_v1_billing_paddle_orders", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleOrderInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Crea o recupera un singolo pagamento di servizio Paddle", "x-licentivo-access": "owner" } }, "/api/v1/billing/paddle/orders/{id}": { "get": { "operationId": "get__api_v1_billing_paddle_orders__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge la transazione di checkout di cui si è titolari e il token client pubblico", "x-licentivo-access": "session" } }, "/api/v1/billing/paddle/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_billing_paddle_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleReconcileInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Verifica il pagamento e fornisce una sola volta il servizio acquistato", "x-licentivo-access": "owner" } }, "/api/v1/billing/paypal/orders": { "get": { "operationId": "get_api_v1_billing_paypal_orders", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "amount_cents": 0, "approval_url": "", "capture_id": null, "created_at": "2026-10-18T00:00:00Z", "credited_at": null, "currency": "USD", "id": "33333333-3333-4333-8333-333333333333", "mode": "sandbox", "paypal_order_id": null, "purchase_id": null, "refunded_cents": 0, "request_id": "55555555-5555-4555-8555-555555555555", "status": "creating", "upgrade_id": null } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrderList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca gli ordini di ricarica", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "post": { "description": "I termini pubblicati richiedono policy_version e l'accettazione esplicita in entrambi gli ambienti di pagamento. Gli sforamenti del servizio a pagamento richiedono inoltre overage_accepted. Prima della prima pubblicazione delle politiche, il consenso alle bozze non viene registrato e ogni operazione continua a seguire le normali verifiche di registrazione, prezzo e pagamento.", "operationId": "post_api_v1_billing_paypal_orders", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RechargeInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrder" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Crea/recupera una ricarica idempotente", "x-required-role": "owner" } }, "/api/v1/billing/paypal/orders/{id}/capture": { "post": { "operationId": "post_api_v1_billing_paypal_orders_by_id_capture", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrder" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Conferma una sola volta i fondi associati al commerciante", "x-required-role": "owner" } }, "/api/v1/billing/paypal/orders/{id}/reconcile": { "post": { "operationId": "post_api_v1_billing_paypal_orders_by_id_reconcile", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrder" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Conferma una sola volta i fondi associati al commerciante", "x-required-role": "owner" } }, "/api/v1/billing/paypal/orders/{id}/refund-requests": { "post": { "description": "Solo sessioni tramite cookie; le chiavi API amministrative non sono accettate. Le letture dei clienti sono limitate al proprio spazio di lavoro. Le scritture dei clienti richiedono un Owner verificato dello spazio di lavoro, senza necessità del permesso di amministratore della piattaforma. Le domande non spostano né riservano fondi. L'approvazione dell'amministratore verifica nuovamente il portafoglio corrente e il valore acquisito non ancora rimborsato, quindi usa la procedura idempotente esistente di rimborso sul metodo originale e prenotazione. L'approvazione non annulla i piani.", "operationId": "post__api_v1_billing_paypal_orders__id__refund_requests", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRefundRequestInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequest" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" } }, "security": [ { "session": [] } ], "summary": "Richiede il rimborso del mio credito di ricarica non speso", "x-required-role": "owner" } }, "/api/v1/billing/plans": { "get": { "operationId": "get_api_v1_billing_plans", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Catalogo prezzi pubblico gestito dall'amministratore" } }, "/api/v1/billing/purchases": { "get": { "operationId": "get_api_v1_billing_purchases", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active": null, "active_devices": 0, "coverage_ends_at": null, "items": [ { "api_calls": 0, "api_hard_limit": false, "api_overage_cents": 0, "api_unit_micros": 0, "base_cents": 0, "cancelled_at": null, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "current_cycle_index": 0, "current_upgrade_id": "", "cycle_ends_at": "2026-10-18T00:00:00Z", "cycle_starts_at": "2026-10-18T00:00:00Z", "effective_included_devices": 0, "effective_plan": "", "effective_plan_name": "", "ends_at": null, "entitlement_cents": 0, "gift_batch_id": "", "gift_follows_current": false, "hard_limit": false, "id": "33333333-3333-4333-8333-333333333333", "included_api_calls": null, "included_devices": 0, "mode": "sandbox", "overage_cents": 0, "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "refunded_cents": 0, "renewal": false, "renewal_of": "", "request_id": "55555555-5555-4555-8555-555555555555", "service_credit_basis_cents": 0, "service_credit_basis_seconds": 0, "source": "purchase", "starts_at": null, "status": "pending", "term_months": 1, "total_api_calls": 0, "total_api_overage_cents": 0, "total_device_overage_cents": 0, "unit_micros": 0 } ], "mode": "sandbox", "renewal_package": null, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PurchaseList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca gli acquisti di pacchetti", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "post": { "description": "Crea un acquisto con il piano, la valuta, la revisione del prezzo e la durata selezionati. Tenta il pagamento immediato tramite portafoglio; se il saldo è insufficiente restituisce pending senza avviare la copertura. Impostare renewal=true per estendere un pacchetto attivo. Il pagamento riuscito programma il servizio dopo la copertura esistente; GET /billing/purchases riporta coverage_ends_at. L'utilizzo della quota corrente e la scadenza delle licenze software rimangono invariati. I tentativi successivi riutilizzano request_id e non possono addebitare due volte. I termini pubblicati richiedono policy_version e l'accettazione esplicita in entrambi gli ambienti di pagamento. Gli sforamenti del servizio a pagamento richiedono inoltre overage_accepted. Prima della prima pubblicazione delle politiche, il consenso alle bozze non viene registrato e ogni operazione continua a seguire le normali verifiche di registrazione, prezzo e pagamento.", "operationId": "post_api_v1_billing_purchases", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyPlan" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanPurchase" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Acquista un pacchetto o paga un rinnovo anticipato", "x-required-role": "owner" } }, "/api/v1/billing/refund-requests": { "get": { "description": "Solo sessioni tramite cookie; le chiavi API amministrative non sono accettate. Le letture dei clienti sono limitate al proprio spazio di lavoro. Le scritture dei clienti richiedono un Owner verificato dello spazio di lavoro, senza necessità del permesso di amministratore della piattaforma. Le domande non spostano né riservano fondi. L'approvazione dell'amministratore verifica nuovamente il portafoglio corrente e il valore acquisito non ancora rimborsato, quindi usa la procedura idempotente esistente di rimborso sul metodo originale e prenotazione. L'approvazione non annulla i piani.", "operationId": "get__api_v1_billing_refund_requests", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequestList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" } }, "security": [ { "session": [] } ], "summary": "Elenca le domande di rimborso del mio spazio di lavoro" } }, "/api/v1/billing/refund-requests/{id}/cancel": { "post": { "description": "Solo sessioni tramite cookie; le chiavi API amministrative non sono accettate. Le letture dei clienti sono limitate al proprio spazio di lavoro. Le scritture dei clienti richiedono un Owner verificato dello spazio di lavoro, senza necessità del permesso di amministratore della piattaforma. Le domande non spostano né riservano fondi. L'approvazione dell'amministratore verifica nuovamente il portafoglio corrente e il valore acquisito non ancora rimborsato, quindi usa la procedura idempotente esistente di rimborso sul metodo originale e prenotazione. L'approvazione non annulla i piani.", "operationId": "post__api_v1_billing_refund_requests__id__cancel", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequest" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" } }, "security": [ { "session": [] } ], "summary": "Ritira la mia domanda di rimborso in sospeso", "x-required-role": "owner" } }, "/api/v1/billing/renewal-plans": { "get": { "description": "Solo titolarità derivante da acquisti completati e upgrade applicati. Restituisce le offerte pubblicate abilitate e le offerte nascoste riservate al rinnovo per i rispettivi clienti esistenti. I preventivi in sospeso non conferiscono titolarità. Rinnovare usando POST /billing/purchases in anticipo o dopo la scadenza.", "operationId": "get__api_v1_billing_renewal_plans", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "api_hard_limit": false, "api_unit_micros": 0, "base_micros": 0, "currency": "USD", "description": "Desktop reporting software", "enabled": true, "hard_limit": false, "included_api_calls": null, "included_devices": 0, "name": "Report app", "plan": "starter", "price_version": "example-v1", "public": false, "renewal_only": false, "sort_order": 0, "terms": [], "unit_micros": 0, "updated_at": "2026-10-18T00:00:00Z" } ], "mode": "sandbox" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RenewalPlans", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca le offerte di rinnovo", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/subscription": { "get": { "operationId": "get_api_v1_billing_subscription", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "current": { "base_covered": false, "base_micros": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "hard_limit": false, "included_devices": 0, "month": "2026-09", "payment_mode": "sandbox", "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "unit_micros": 0 }, "next": null, "sandbox": false }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Subscription", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "La quota predefinita è disabilitata (DEFAULT_PLAN_DISABLED)" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Legge l'abbonamento mensile", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "patch": { "operationId": "patch_api_v1_billing_subscription", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "currency": "USD", "plan": "starter", "price_version": "example-v1" }, "schema": { "$ref": "#/components/schemas/PlanChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "currency": "USD", "effective_month": "2026-11", "plan": "starter", "sandbox": false }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ScheduledPlan", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Programma il piano mensile", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/upgrades": { "get": { "description": "", "operationId": "get__api_v1_billing_upgrades", "parameters": [ { "in": "query", "name": "limit", "schema": { "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "amount_cents": 0, "api_hard_limit": false, "api_unit_micros": 0, "applied_at": null, "base_cents": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "cycle_seconds": 0, "ends_at": "2026-10-18T00:00:00Z", "expires_at": "2026-10-18T00:00:00Z", "hard_limit": false, "id": "33333333-3333-4333-8333-333333333333", "included_api_calls": null, "included_devices": 0, "mode": "sandbox", "parent_id": "33333333-3333-4333-8333-333333333333", "parts": [], "plan": "starter", "plan_name": "Starter", "previous_base_cents": 0, "previous_plan_name": "", "previous_upgrade_id": "", "price_version": "example-v1", "purchase_id": "33333333-3333-4333-8333-333333333333", "remaining_seconds": 0, "request_id": "55555555-5555-4555-8555-555555555555", "status": "pending", "unit_micros": 0 } ], "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/UpgradeList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "422": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "502": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca gli upgrade dei pacchetti", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/upgrades/quote": { "post": { "description": "Richiede una sessione Owner. Il piano di destinazione deve usare la stessa valuta e non deve avere un prezzo mensile o quote dispositivi/API inferiori. Conserva la scadenza e l'utilizzo originali. L'upgrade include sempre la copertura corrente e tutta quella futura prepagata/regalata. Ogni periodo accredita il valore originario del beneficio, calcolato pro rata sui secondi rimanenti; per un periodo non ancora iniziato si usa l'intera durata. Il valore dei regali non è denaro rimborsabile. Il pagamento è un singolo addebito atomico sul portafoglio; le date e la quota consumata rimangono invariate. Rinnovi, regali o annullamenti tra il preventivo e il pagamento invalidano il preventivo con UPGRADE_STATE_CONFLICT; una ricarica PayPal collegata e giunta in ritardo rimane come credito nel portafoglio. Una modifica della copertura richiede un nuovo preventivo.", "operationId": "post__api_v1_billing_upgrades_quote", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeQuoteInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanUpgrade" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." } }, "security": [ { "session": [] } ], "summary": "Mostra un'anteprima dell'upgrade del piano calcolato pro rata, senza addebitare il portafoglio" } }, "/api/v1/billing/upgrades/{id}/pay": { "post": { "description": "Restituisce pending senza modificare il piano se il saldo è insufficiente. Restituisce applied dopo un unico addebito. Se il piano attivo è cambiato o il preventivo è scaduto, restituisce 409. L'upgrade include sempre la copertura corrente e tutta quella futura prepagata/regalata. Ogni periodo accredita il valore originario del beneficio, calcolato pro rata sui secondi rimanenti; per un periodo non ancora iniziato si usa l'intera durata. Il valore dei regali non è denaro rimborsabile. Il pagamento è un singolo addebito atomico sul portafoglio; le date e la quota consumata rimangono invariate. Rinnovi, regali o annullamenti tra il preventivo e il pagamento invalidano il preventivo con UPGRADE_STATE_CONFLICT; una ricarica PayPal collegata e giunta in ritardo rimane come credito nel portafoglio. Una modifica della copertura richiede un nuovo preventivo. Prima di un nuovo pagamento è richiesta l'accettazione esplicita della politica corrente. La ripetizione di un pagamento già effettuato conserva la ricevuta originale.", "operationId": "post__api_v1_billing_upgrades__id__pay", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalConsent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanUpgrade" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." } }, "security": [ { "session": [] } ], "summary": "Conferma e paga una sola volta un preventivo di upgrade valido" } }, "/api/v1/billing/waffo/orders": { "get": { "operationId": "get__api_v1_billing_waffo_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderList" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Elenca i pagamenti di servizi e le ricariche del portafoglio Waffo", "x-licentivo-access": "session" }, "post": { "operationId": "post__api_v1_billing_waffo_orders", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaffoOrderInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Crea o recupera un singolo pagamento di servizio Waffo", "x-licentivo-access": "owner" } }, "/api/v1/billing/waffo/orders/{id}": { "get": { "operationId": "get__api_v1_billing_waffo_orders__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge il checkout Waffo del proprio spazio di lavoro", "x-licentivo-access": "session" } }, "/api/v1/billing/waffo/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_billing_waffo_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Verifica il pagamento e riconcilia il servizio e i rimborsi", "x-licentivo-access": "owner" } }, "/api/v1/billing/wallet": { "get": { "operationId": "get_api_v1_billing_wallet", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "currencies": [], "items": [ { "balance_cents": 0, "currency": "USD", "mode": "sandbox" } ], "maximum_cents": 0, "minimum_cents": 0, "mode": "sandbox", "payment_channels": [], "paypal_enabled": false }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletResult", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Legge i saldi del portafoglio", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/wallet/entries": { "get": { "operationId": "get_api_v1_billing_wallet_entries", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "amount_cents": 0, "balance_cents": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "id": "33333333-3333-4333-8333-333333333333", "kind": "", "mode": "sandbox", "reference": "" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletEntryList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca i movimenti del portafoglio", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/consume": { "post": { "description": "Operazione di esecuzione autenticata tramite licenza; nessun cookie del fornitore o API Key. Il consumo delle funzionalità richiede un Idempotency-Key stabile; consume non comporta addebiti API della piattaforma.", "operationId": "post_api_v1_consume", "parameters": [ { "description": "Generare una nuova chiave per ogni operazione; i tentativi successivi conservano la stessa chiave e lo stesso corpo. Massimo 80 caratteri, senza spazi bianchi. Facoltativa per la convalida e l'heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ConsumptionResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "/consume" } }, "/api/v1/consume/cancel": { "post": { "description": "Prenotare prima dell'operazione applicativa, confermare solo dopo il successo e annullare in caso di errore. Conservare lo stesso identificativo dell'attività e lo stesso corpo della richiesta tra i tentativi. Un timeout di commit lascia un esito incerto: riprovare commit, senza annullare né ripetere il lavoro già completato. Le prenotazioni concluse restituiscono il proprio stato corrente; nessun addebito API della piattaforma. Il completamento emette license.consume; le prenotazioni provvisorie non emettono eventi di consumo.", "operationId": "post_api_v1_consume_cancel", "parameters": [ { "description": "Generare una nuova chiave per ogni operazione; i tentativi successivi conservano la stessa chiave e lo stesso corpo. Massimo 80 caratteri, senza spazi bianchi. Facoltativa per la convalida e l'heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReservationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Unità delle funzionalità: annullamento" } }, "/api/v1/consume/commit": { "post": { "description": "Prenotare prima dell'operazione applicativa, confermare solo dopo il successo e annullare in caso di errore. Conservare lo stesso identificativo dell'attività e lo stesso corpo della richiesta tra i tentativi. Un timeout di commit lascia un esito incerto: riprovare commit, senza annullare né ripetere il lavoro già completato. Le prenotazioni concluse restituiscono il proprio stato corrente; nessun addebito API della piattaforma. Il completamento emette license.consume; le prenotazioni provvisorie non emettono eventi di consumo.", "operationId": "post_api_v1_consume_commit", "parameters": [ { "description": "Generare una nuova chiave per ogni operazione; i tentativi successivi conservano la stessa chiave e lo stesso corpo. Massimo 80 caratteri, senza spazi bianchi. Facoltativa per la convalida e l'heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReservationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Unità delle funzionalità: conferma" } }, "/api/v1/consume/reserve": { "post": { "description": "Prenotare prima dell'operazione applicativa, confermare solo dopo il successo e annullare in caso di errore. Conservare lo stesso identificativo dell'attività e lo stesso corpo della richiesta tra i tentativi. Un timeout di commit lascia un esito incerto: riprovare commit, senza annullare né ripetere il lavoro già completato. Le prenotazioni concluse restituiscono il proprio stato corrente; nessun addebito API della piattaforma. Il completamento emette license.consume; le prenotazioni provvisorie non emettono eventi di consumo.", "operationId": "post_api_v1_consume_reserve", "parameters": [ { "description": "Generare una nuova chiave per ogni operazione; i tentativi successivi conservano la stessa chiave e lo stesso corpo. Massimo 80 caratteri, senza spazi bianchi. Facoltativa per la convalida e l'heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReservationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Unità delle funzionalità: prenotazione" } }, "/api/v1/customer/activations/{id}/release": { "post": { "operationId": "post_api_v1_customer_activations_by_id_release", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReleaseInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerReleaseResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "customerSession": [] } ], "summary": "/customer/activations/{id}/release" } }, "/api/v1/customer/cases": { "get": { "description": "", "operationId": "get__api_v1_customer_cases", "parameters": [ { "description": "Esclude un tipo di richiesta prima del conteggio e della paginazione. Usare refund per escludere i casi di rimborso dall'elenco dell'assistenza; l'accesso rimane limitato alla sessione corrente.", "in": "query", "name": "exclude_kind", "schema": { "maxLength": 24, "type": "string" } }, { "description": "Limita i casi di rimborso alle ricariche del portafoglio o all'annullamento del servizio.", "in": "query", "name": "refund_scope", "required": false, "schema": { "enum": [ "wallet", "service" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Elenca le richieste dei clienti", "x-required-role": "session" }, "post": { "description": "Un request_id stabile è limitato allo spazio di lavoro; contenuti modificati non possono riutilizzarlo.", "operationId": "post__api_v1_customer_cases", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCase" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Crea una richiesta di assistenza, privacy o ricorso", "x-required-role": "session" } }, "/api/v1/customer/cases/unread": { "get": { "description": "Le chat sui rimborsi sono escluse. I clienti vedono soltanto i ticket autorizzati dello spazio di lavoro; i membri vedono i propri. Ogni amministratore ha un indicatore di lettura indipendente.", "operationId": "get__api_v1_customer_cases_unread", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportUnread" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge i conteggi personali dei ticket e degli avvisi non letti", "x-required-role": "session" } }, "/api/v1/customer/cases/{id}": { "get": { "description": "", "operationId": "get__api_v1_customer_cases__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge una richiesta e le risposte", "x-required-role": "session" } }, "/api/v1/customer/cases/{id}/messages": { "post": { "description": "I casi di rimborso rifiutano le risposte con REFUND_REVIEW_WORKFLOW; gli amministratori approvano o respingono direttamente. I normali ticket di assistenza conservano le risposte. Le chiusure già esaminate mantengono il proprio stato nella procedura di privacy.", "operationId": "post__api_v1_customer_cases__id__messages", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReply" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Risponde a un ticket di assistenza", "x-required-role": "session" } }, "/api/v1/customer/cases/{id}/read": { "post": { "description": "Vengono contrassegnati come letti soltanto i messaggi fino all'ultimo visualizzato. Quelli arrivati successivamente rimangono non letti e le conferme ritardate non possono far arretrare l'indicatore di lettura.", "operationId": "post__api_v1_customer_cases__id__read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReadInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Conferma la lettura dei messaggi del ticket visualizzati", "x-required-role": "session" } }, "/api/v1/customer/compensations": { "get": { "description": "", "operationId": "get__api_v1_customer_compensations", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "incident_id": "33333333-3333-4333-8333-333333333333", "intervals": "", "mode": "timed", "purchase_id": "33333333-3333-4333-8333-333333333333", "seconds": 0 } ] }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceCompensationList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca le compensazioni del servizio", "x-management-reference": { "group": "service" }, "x-required-role": "session", "x-required-scope": "read" } }, "/api/v1/customer/licenses": { "get": { "operationId": "get_api_v1_customer_licenses", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerLicenses" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "customerSession": [] } ], "summary": "Licenze associate all'acquirente" } }, "/api/v1/customer/login": { "post": { "operationId": "post_api_v1_customer_login", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "/customer/login" } }, "/api/v1/customer/logout": { "post": { "operationId": "post_api_v1_customer_logout", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoggedOut" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "customerSession": [] } ], "summary": "/customer/logout" } }, "/api/v1/customer/notices": { "get": { "description": "", "operationId": "get__api_v1_customer_notices", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "body": "", "created_at": "2026-10-18T00:00:00Z", "effective_at": null, "emailed_at": null, "id": "33333333-3333-4333-8333-333333333333", "kind": "", "read_at": null, "reference": "", "title": "" } ] }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceNoticeList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca gli avvisi di servizio", "x-management-reference": { "group": "service" }, "x-required-role": "session", "x-required-scope": "read" } }, "/api/v1/customer/notices/{id}/read": { "post": { "description": "", "operationId": "post__api_v1_customer_notices__id__read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Contrassegna un proprio avviso come letto", "x-required-role": "session" } }, "/api/v1/customer/offline/respond": { "post": { "operationId": "post_api_v1_customer_offline_respond", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OfflineResponse" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "customerSession": [] } ], "summary": "/customer/offline/respond" } }, "/api/v1/customer/refunds": { "post": { "description": "Un ambito esplicito richiede la conferma insieme ai valori quote_hash e quoted_at restituiti. Il servizio rimane attivo fino all'approvazione dell'amministratore. Uno stato modificato o preventivi scaduti richiedono una nuova anteprima; le domande in sospeso in conflitto vengono rifiutate. Le richieste prive di ambito consentono l'annullamento immediato, se idoneo, dopo una conferma esplicita. Un order_id può anche selezionare un pagamento Waffo/Paddle paid_unapplied con reason=failed_delivery; non blocca credito del portafoglio mai concesso.", "operationId": "post__api_v1_customer_refunds", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRefundInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCase" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Invia una domanda di rimborso per la revisione diretta", "x-required-role": "owner" } }, "/api/v1/customer/refunds/quote": { "post": { "description": "Un ambito esplicito di acquisto/servizio restituisce l'hash di un'istantanea delimitata, gli acquisti interessati, le stime dei rimborsi per valuta e le date rimanenti. L'invio non interrompe il servizio. I regali non hanno valore in denaro; gli upgrade pagati rimangono rimborsabili previa revisione.", "operationId": "post__api_v1_customer_refunds_quote", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRefundQuoteInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerRefundQuote" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Mostra un'anteprima dell'ambito di annullamento, dei rimborsi e del servizio rimanente", "x-required-role": "owner" } }, "/api/v1/customer/refunds/{id}/cancel": { "post": { "operationId": "post__api_v1_customer_refunds__id__cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelCustomerRefund" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" } }, "security": [ { "session": [] } ], "summary": "Ritira la parte rimanente della mia richiesta di rimborso non ancora esaminata", "x-required-role": "owner" } }, "/api/v1/customer/verify": { "post": { "operationId": "post_api_v1_customer_verify", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerSession" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "/customer/verify" } }, "/api/v1/deactivate": { "post": { "description": "Autenticazione tramite product_id + license_key + device_id. Nessun cookie/CSRF/chiave del fornitore. activation_id è obbligatorio tranne che per activate. Ogni richiesta riuscita consuma una chiamata API; le ripetizioni idempotenti e gli errori non consumano chiamate. Gli sforamenti addebitano il portafoglio in modo atomico oppure restituiscono API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT. La quota dei dispositivi dello spazio di lavoro segue le attivazioni correnti. Il rilascio restituisce capacità; anche la scadenza di un lease flottante restituisce capacità, mentre una registrazione ordinaria offline continua a essere conteggiata. Gli sforamenti dei dispositivi vengono addebitati soltanto quando il picco di fatturazione del mese della quota supera la capacità già pagata; il rilascio non rimborsa i costi già sostenuti. L'utilizzo delle API è separato.", "operationId": "post_api_v1_deactivate", "parameters": [ { "description": "Generare una nuova chiave per ogni operazione; i tentativi successivi conservano la stessa chiave e lo stesso corpo. Massimo 80 caratteri, senza spazi bianchi. Facoltativa per la convalida e l'heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Disattivazione in fase di esecuzione" } }, "/api/v1/demo/trial": { "post": { "operationId": "post_api_v1_demo_trial", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Trial" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Crea una prova SDK isolata di sette giorni per ogni proprietario", "x-required-role": "owner" } }, "/api/v1/examples/sdk": { "get": { "operationId": "get_api_v1_examples_sdk", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKExampleInfo" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Disponibilità pubblica degli esempi SDK" } }, "/api/v1/examples/sdk/download/{name}": { "get": { "operationId": "get_api_v1_examples_sdk_download_{name}", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "description": "Linguaggio seguito da .zip, ad esempio csharp.zip", "type": "string" } } ], "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Scarica il codice sorgente con le impostazioni pubbliche del prodotto già incluse nel codice" } }, "/api/v1/examples/sdk/trial": { "post": { "description": "Richiede il token CSRF del browser e un cookie visitatore HttpOnly. Ogni visitatore riceve una licenza separata; i tre giorni iniziano alla prima attivazione. Le richieste ripetute non estendono mai la scadenza. Abilita export, non pro.", "operationId": "post_api_v1_examples_sdk_trial", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKExampleTrial" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Richiede/recupera la prova indipendente di tre giorni di questo visitatore" } }, "/api/v1/forum/images": { "post": { "operationId": "post__api_v1_forum_images", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "image": { "description": "PNG, JPEG o GIF; al massimo 5 MB, 4096 × 4096 e 16 milioni di pixel. I GIF vengono salvati come PNG statici. Privata finché non viene allegata a un post pubblicato.", "format": "binary", "type": "string" } }, "required": [ "image" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumImage" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" } }, "security": [ { "session": [] } ], "summary": "Carica un'immagine privata in bozza", "tags": [ "Community" ] } }, "/api/v1/forum/replies/{id}": { "delete": { "operationId": "delete__api_v1_forum_replies__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" } }, "security": [ { "session": [] } ], "summary": "Elimina una risposta (autore o amministratore della piattaforma)", "tags": [ "Community" ] }, "patch": { "operationId": "patch__api_v1_forum_replies__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumReplyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" } }, "security": [ { "session": [] } ], "summary": "Modifica una propria risposta", "tags": [ "Community" ] } }, "/api/v1/forum/topics": { "get": { "operationId": "get__api_v1_forum_topics", "parameters": [ { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "in": "query", "name": "category", "schema": { "type": "string" } }, { "in": "query", "name": "language", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumTopicList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" } }, "security": [], "summary": "Elenca le discussioni pubbliche, prima quelle in evidenza", "tags": [ "Community" ] }, "post": { "operationId": "post__api_v1_forum_topics", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumTopicInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" } }, "security": [ { "session": [] } ], "summary": "Crea una discussione (qualsiasi membro verificato del tenant)", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}": { "delete": { "operationId": "delete__api_v1_forum_topics__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" } }, "security": [ { "session": [] } ], "summary": "Elimina una discussione (autore o amministratore della piattaforma)", "tags": [ "Community" ] }, "get": { "operationId": "get__api_v1_forum_topics__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumTopicDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" } }, "security": [], "summary": "Legge una discussione pubblica e le risposte", "tags": [ "Community" ] }, "patch": { "operationId": "patch__api_v1_forum_topics__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumTopicInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" } }, "security": [ { "session": [] } ], "summary": "Modifica una propria discussione", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}/moderation": { "post": { "operationId": "post__api_v1_forum_topics__id__moderation", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumModerationInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" } }, "security": [ { "session": [] } ], "summary": "Mette in evidenza, rimuove dall'evidenza, nasconde o blocca le discussioni (amministratore della piattaforma)", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}/replies": { "post": { "operationId": "post__api_v1_forum_topics__id__replies", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumReplyInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codice di errore e ID della richiesta; nessun dettaglio dell'account esposto" } }, "security": [ { "session": [] } ], "summary": "Risponde a una discussione", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}/translate": { "post": { "description": "I visitatori anonimi possono usare questo endpoint con un token CSRF. Viene accettato soltanto il testo pubblicato e memorizzato del forum, mai testo arbitrario inviato nella richiesta. La traduzione viene memorizzata nella cache per contenuto e lingua di destinazione. Gli argomenti/le risposte nascosti restituiscono 404; una traduzione concorrente può restituire TRANSLATION_PENDING. Gli originali vengono conservati.", "operationId": "post__api_v1_forum_topics__id__translate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumTranslationInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumTranslationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." } }, "security": [], "summary": "Traduce un argomento o una risposta pubblicati" } }, "/api/v1/forum/translation": { "get": { "description": "", "operationId": "get__api_v1_forum_translation", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationOptions" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." } }, "security": [], "summary": "Ottiene le lingue di destinazione delle traduzioni disponibili pubblicamente" } }, "/api/v1/heartbeat": { "post": { "description": "Autenticazione tramite product_id + license_key + device_id. Nessun cookie/CSRF/chiave del fornitore. activation_id è obbligatorio tranne che per activate. Ogni richiesta riuscita consuma una chiamata API; le ripetizioni idempotenti e gli errori non consumano chiamate. Gli sforamenti addebitano il portafoglio in modo atomico oppure restituiscono API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT. Le ricevute dei tentativi successivi di convalida e heartbeat scadono dopo 3600 secondi. Finché l'autorizzazione originale rimane valida, le richieste corrispondenti entro questa finestra riproducono il risultato senza un ulteriore addebito. Dopo la finestra usare una nuova chiave; una chiave già usata può essere elaborata come una nuova richiesta. Le ricevute di attivazione, disattivazione e utilizzo delle funzionalità rimangono persistenti. La quota dei dispositivi dello spazio di lavoro segue le attivazioni correnti. Il rilascio restituisce capacità; anche la scadenza di un lease flottante restituisce capacità, mentre una registrazione ordinaria offline continua a essere conteggiata. Gli sforamenti dei dispositivi vengono addebitati soltanto quando il picco di fatturazione del mese della quota supera la capacità già pagata; il rilascio non rimborsa i costi già sostenuti. L'utilizzo delle API è separato.", "operationId": "post_api_v1_heartbeat", "parameters": [ { "description": "Generare una nuova chiave per ogni operazione; i tentativi successivi conservano la stessa chiave e lo stesso corpo. Massimo 80 caratteri, senza spazi bianchi. Facoltativa per la convalida e l'heartbeat.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Heartbeat in fase di esecuzione" } }, "/api/v1/launch/connections": { "get": { "description": "Elenca le connessioni di fiducia Launch. Le decisioni, i tentativi successivi e i controlli dell'ambito vengono eseguiti da Licentivo.", "operationId": "launch_get__api_v1_launch_connections", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "Risultato di questa operazione.", "properties": { "items": { "description": "Record corrispondenti nell'ambito richiesto.", "items": { "$ref": "#/components/schemas/LaunchConnection" }, "type": "array" } }, "required": [], "type": "object" }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Elenca le connessioni di fiducia Launch", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" }, "post": { "description": "Registra un emittente Launch e un ambiente commerciale. Le decisioni, i tentativi successivi e i controlli dell'ambito vengono eseguiti da Licentivo.", "operationId": "launch_post__api_v1_launch_connections", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "issuer": "https://shop.example.test", "public_keys": { "launch-1": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "schema": { "$ref": "#/components/schemas/LaunchConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "id": "11111111-1111-4111-8111-111111111111", "issuer": "https://shop.example.test" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchConnection", "description": "Risultato di questa operazione." }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Registra un emittente Launch e un ambiente commerciale", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}": { "put": { "description": "L'emittente, il destinatario e l'ambiente sono immutabili. Fornire l'intero insieme di chiavi pubbliche attendibili.", "operationId": "launch_put__api_v1_launch_connections_id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "issuer": "https://shop.example.test", "public_keys": { "launch-1": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "schema": { "$ref": "#/components/schemas/LaunchConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "id": "11111111-1111-4111-8111-111111111111", "issuer": "https://shop.example.test" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchConnection", "description": "Risultato di questa operazione." }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Ruota le chiavi Launch o aggiorna i limiti di esecuzione", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/devices/{activation}/release": { "post": { "description": "Licentivo riserva la quota di rilascio autonomo di 30 giorni, registra l'operazione e gestisce i tentativi successivi e la revisione manuale. Il worker confronta la versione dell'associazione e revoca le sessioni e le credenziali sotto gli stessi blocchi transazionali. Le vecchie sessioni di accesso Launch non possono scambiare un'altra attestazione di identità sul dispositivo revocato.", "operationId": "launch_post__api_v1_launch_connections_id_devices_activation_release", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "activation", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_ref": "account_ref_example", "entitlement_ref": "entitlement_ref_example", "environment": "live", "expected_generation": 1, "operation_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LaunchDeviceReleaseInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "license_id": "11111111-1111-4111-8111-111111111111", "operation_id": "11111111-1111-4111-8111-111111111111", "source": "logout", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeviceReleaseOperation", "description": "Risultato di questa operazione." }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Richiede un rilascio remoto con versione di un dispositivo dell'account", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/entitlements/{entitlement}/devices": { "get": { "description": "Legge i dispositivi dell'account, la quota di rilascio autorevole e le operazioni. Le decisioni, i tentativi successivi e i controlli dell'ambito vengono eseguiti da Licentivo.", "operationId": "launch_get__api_v1_launch_connections_id_entitlements_entitlement_devices", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "entitlement", "required": true, "schema": { "description": "Riferimento immutabile del diritto di acquisto, con distinzione tra maiuscole e minuscole.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, { "in": "query", "name": "account_ref", "required": true, "schema": { "description": "Riferimento immutabile del diritto di acquisto, con distinzione tra maiuscole e minuscole.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, { "in": "query", "name": "environment", "required": true, "schema": { "description": "Ambiente commerciale, fissato sia nella connessione sia nell'autorizzazione firmata.", "enum": [ "live", "sandbox" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "Risultato di questa operazione.", "properties": { "can_release": { "description": "Indica se questa connessione di fiducia può autorizzare nuovi utilizzi in fase di esecuzione.", "type": "boolean" }, "items": { "description": "Record corrispondenti nell'ambito richiesto.", "items": { "additionalProperties": false, "properties": { "device_name": { "description": "Etichetta del dispositivo leggibile dall'utente.", "type": "string" }, "generation": { "description": "Incarnazione corrente dell'associazione del dispositivo.", "type": "integer" }, "id": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" }, "last_seen_at": { "description": "Ora di creazione del record in UTC.", "format": "date-time", "type": "string" }, "status": { "description": "Stato corrente del ciclo di vita o dell'elaborazione, gestito dal server.", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "operations": { "description": "Cronologia delle operazioni di rilascio dei dispositivi gestita dal server.", "items": { "$ref": "#/components/schemas/DeviceReleaseOperation" }, "type": "array" }, "remaining": { "description": "Rilasci autonomi rimanenti negli ultimi 30 giorni, calcolati da Licentivo.", "type": "integer" } }, "required": [], "type": "object" }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Legge i dispositivi dell'account, la quota di rilascio autorevole e le operazioni", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/connections/{id}/events": { "post": { "description": "Salvare in modo persistente prima di confermare la ricezione. ID duplicati con corpi diversi generano un conflitto. I worker applicano in modo transazionale la validità assoluta e le versioni aggregate monotone, ignorano le versioni precedenti e riprovano gli errori fino a 12 tentativi prima della revisione manuale. Per un diritto esistente, rimborsi, sospensione e scadenza revocano l'accesso indipendentemente dalle mappature dei piani, dalle versioni delle politiche, dalle modalità di validità e dall'occupazione dei dispositivi, mantenendo i controlli di titolarità e versione. I downgrade dei piani applicano insieme le nuove funzionalità, le regole di misurazione e il limite effettivo dei dispositivi, conservano le associazioni più vecchie e revocano le sessioni e le credenziali dei dispositivi in eccesso senza consumare la quota di rilascio autonomo. Rinnovi, modifiche dei piani e salvataggi delle politiche conservano i limiti manuali indipendenti delle funzionalità e dei dispositivi. Le istantanee esplicite entitlement.downgraded mantengono lo stato commerciale attivo, ma bloccano in modo persistente i vecchi diritti se l'applicazione fallisce. Le istantanee attive esistenti con riduzioni dimostrabili ricevono la stessa protezione. Solo un'istantanea applicata con versione pari o superiore alla restrizione in sospeso rimuove tale barriera. I tentativi idempotenti in fase di esecuzione conservano la deduplicazione delle operazioni aggiornando al contempo le autorizzazioni e le scadenze degli acquisti modificate. Consultare periodicamente l'evento prima di dichiarare pronta l'autorizzazione.", "operationId": "launch_post__api_v1_launch_connections_id_events", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_ref": "account_ref_example", "entitlement_ref": "entitlement_ref_example", "environment": "live", "event_id": "11111111-1111-4111-8111-111111111111", "launch_product_id": "11111111-1111-4111-8111-111111111111", "plan_ref": "plan_ref_example", "type": "entitlement.created", "valid_from": "2026-10-24T00:00:00Z", "version": 1 }, "schema": { "$ref": "#/components/schemas/LaunchCommerceEvent" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "attempts": 1, "available_at": "2026-10-24T00:00:00Z", "connection_id": "11111111-1111-4111-8111-111111111111", "event_id": "11111111-1111-4111-8111-111111111111", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchEvent", "description": "Risultato di questa operazione." }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Riceve un'istantanea commerciale completa di Launch", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/events/{event}": { "get": { "description": "Legge il risultato di un evento commerciale Launch. Le decisioni, i tentativi successivi e i controlli dell'ambito vengono eseguiti da Licentivo.", "operationId": "launch_get__api_v1_launch_connections_id_events_event_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "event", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "attempts": 1, "available_at": "2026-10-24T00:00:00Z", "connection_id": "11111111-1111-4111-8111-111111111111", "event_id": "11111111-1111-4111-8111-111111111111", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchEvent", "description": "Risultato di questa operazione." }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Legge il risultato di un evento commerciale Launch", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/connections/{id}/events/{event}/retry": { "post": { "description": "Riprova un evento Launch non applicato. Le decisioni, i tentativi successivi e i controlli dell'ambito vengono eseguiti da Licentivo.", "operationId": "launch_post__api_v1_launch_connections_id_events_event_retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "event", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "Risultato di questa operazione.", "properties": { "queued": { "description": "Indica se questa connessione di fiducia può autorizzare nuovi utilizzi in fase di esecuzione.", "type": "boolean" } }, "required": [], "type": "object" }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Riprova un evento Launch non applicato", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/plans/{plan}": { "put": { "description": "Mappa una versione del piano Launch a una politica di licenza. Le decisioni, i tentativi successivi e i controlli dell'ambito vengono eseguiti da Licentivo.", "operationId": "launch_put__api_v1_launch_connections_id_plans_plan_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "plan", "required": true, "schema": { "description": "Riferimento immutabile del diritto di acquisto, con distinzione tra maiuscole e minuscole.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "launch_product_id": "11111111-1111-4111-8111-111111111111", "policy_id": "11111111-1111-4111-8111-111111111111", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LaunchPlanMappingInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "Risultato di questa operazione.", "properties": { "saved": { "description": "Indica se questa connessione di fiducia può autorizzare nuovi utilizzi in fase di esecuzione.", "type": "boolean" } }, "required": [], "type": "object" }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Mappa una versione del piano Launch a una politica di licenza", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/session-revocations": { "post": { "description": "Revoca atomica sincrona: HTTP 200 indica che sono stati confermati le sessioni, le credenziali, le associazioni dei dispositivi corrispondenti e la ricevuta persistente. La connessione determina l'ambiente; un eventuale ambiente non vuoto deve corrispondere. L'omissione e un valore esplicito corrispondente sono equivalenti per l'idempotenza. Per i tentativi successivi, anche concorrenti, riutilizzare event_id e lo stesso corpo normalizzato; corpi diversi generano un conflitto. Le ripetizioni riuscite restituiscono i conteggi originali e non revocano gli accessi più recenti. Gli account/sid sconosciuti riescono con zero righe interessate e conservano un marcatore di rifiuto dell'accesso. L'ambito account registra una soglia temporale di autenticazione all'orario di accettazione del server. La validità dei diritti acquistati e i termini delle licenze vengono conservati. Le connessioni disabilitate accettano le revoche.", "operationId": "launch_post__api_v1_launch_connections_id_session_revocations", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_ref": "account_456", "event_id": "11111111-1111-4111-8111-111111111111", "reason": "forced_logout", "scope": "session", "sid": "login_123" }, "schema": { "$ref": "#/components/schemas/LaunchSessionRevocationInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "account_ref": "account_456", "completed_at": "2026-10-24T05:00:00.145678Z", "connection_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-24T05:00:00.123456Z", "environment": "live", "event_id": "11111111-1111-4111-8111-111111111111", "reason": "forced_logout", "released_devices": 2, "revoked_credentials": 2, "revoked_sessions": 2, "scope": "session", "sid": "login_123", "status": "succeeded" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchSessionRevocation", "description": "Risultato di questa operazione." }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "404": { "description": "La connessione non esiste in questo tenant" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "415": { "description": "Usare Content-Type: application/json" }, "500": { "description": "Errore del database o esito sconosciuto; consultare o riprovare l'evento originale senza modificarne l'ID o il corpo" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Revoca un accesso Launch o tutte le sessioni di autorizzazione dell'account", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/session-revocations/{event}": { "get": { "description": "Restituisce la ricevuta persistente originale per questo tenant e questa connessione. HTTP 404 indica che al momento non è visibile alcun risultato confermato; riprovare il POST originale con lo stesso event_id e lo stesso corpo. Non è richiesto alcun worker asincrono.", "operationId": "launch_get__api_v1_launch_connections_id_session_revocations_event_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "event", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "account_ref": "account_456", "completed_at": "2026-10-24T05:00:00.145678Z", "connection_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-24T05:00:00.123456Z", "environment": "live", "event_id": "11111111-1111-4111-8111-111111111111", "reason": "forced_logout", "released_devices": 2, "revoked_credentials": 2, "revoked_sessions": 2, "scope": "session", "sid": "login_123", "status": "succeeded" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchSessionRevocation", "description": "Risultato di questa operazione." }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "404": { "description": "Non esiste alcun risultato confermato per questo tenant e questa connessione" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "500": { "description": "Errore del database o esito sconosciuto; consultare o riprovare l'evento originale senza modificarne l'ID o il corpo" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Consulta il risultato confermato di una revoca di sessione Launch", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/device-operations/{operation}": { "get": { "description": "Legge l'avanzamento del rilascio remoto. Le decisioni, i tentativi successivi e i controlli dell'ambito vengono eseguiti da Licentivo.", "operationId": "launch_get__api_v1_launch_device_operations_operation_", "parameters": [ { "in": "path", "name": "operation", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "license_id": "11111111-1111-4111-8111-111111111111", "operation_id": "11111111-1111-4111-8111-111111111111", "source": "logout", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeviceReleaseOperation", "description": "Risultato di questa operazione." }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Legge l'avanzamento del rilascio remoto", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/device-operations/{operation}/retry": { "post": { "description": "Un'operazione manual_review richiede approve=true da parte del proprietario. L'approvazione non aggira mai la versione originale dell'associazione.", "operationId": "launch_post__api_v1_launch_device_operations_operation_retry", "parameters": [ { "in": "path", "name": "operation", "required": true, "schema": { "description": "UUID della risorsa Licentivo.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": { "approve": { "description": "Indica se questa connessione di fiducia può autorizzare nuovi utilizzi in fase di esecuzione.", "type": "boolean" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "Risultato di questa operazione.", "properties": { "queued": { "description": "Indica se questa connessione di fiducia può autorizzare nuovi utilizzi in fase di esecuzione.", "type": "boolean" } }, "required": [], "type": "object" }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Riprova o approva esplicitamente un rilascio sottoposto a revisione", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/exchange": { "post": { "description": "Idempotency-Key è obbligatorio. Sono richiesti l'header JWT alg=Ed25519, typ=licentivo-launch-identity+jwt e un kid fissato, oltre ai valori esatti di iss/aud/environment, sub, sid, jti, iat, nbf, exp, auth_time, session_exp, launch_product_id, product_id ed entitlement_ref. La durata dell'attestazione è al massimo di 120 secondi. Le ripetizioni recuperano soltanto la stessa sessione attiva del dispositivo con la stessa richiesta e chiave di idempotenza. Gli acquisti vengono letti esclusivamente da Licentivo.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "Idempotency-Key per questa operazione di autorizzazione Launch.", "maxLength": 80, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "environment": "live", "identity_token": "identity_token_example", "launch_connection_id": "11111111-1111-4111-8111-111111111111", "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LaunchExchangeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult", "description": "Risultato di questa operazione." }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [], "summary": "Scambia l'identità dell'account Launch con un'autorizzazione del dispositivo", "tags": [ "Launch account licensing" ] } }, "/api/v1/legal/policy": { "get": { "description": "Restituisce documenti di servizio, rimborso e privacy congelati in tutte le 13 lingue supportate. I dati facoltativi del profilo non confermati vengono omessi. Una versione pubblicata richiede l'accettazione esplicita; le procedure esistenti continuano fino alla prima pubblicazione.", "operationId": "get__api_v1_legal_policy", "parameters": [ { "in": "query", "name": "version", "schema": { "type": "string" } }, { "in": "query", "name": "locale", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommercePolicy" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [], "summary": "Legge una politica legale immutabile" } }, "/api/v1/licenses": { "get": { "operationId": "get_api_v1_licenses", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "product_id", "schema": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "q", "schema": { "description": "Testo di ricerca; i campi interessati e la lunghezza massima dipendono dall'operazione.", "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "active", "expired", "suspended", "revoked" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "customer": "Order #1001", "duration_days": 30, "expires_at": null, "features": [ "export" ], "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key_prefix": "lv_lic_AAAAAAA", "max_devices": 1, "mode": "timed", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "status": "active", "updated_at": "2026-10-18T00:00:00Z" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca le licenze", "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" }, "post": { "description": "Richiede una sessione Owner o una chiave di scrittura di un Owner attivo. Nessun tentativo automatico con Idempotency-Key.", "operationId": "post_api_v1_licenses", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LicenseCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseSecret", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Emette una licenza", "x-management-reference": { "group": "licenses" }, "x-request-variants": [ { "name": "timed", "request": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "response": { "data": { "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "perpetual", "request": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": null, "policy_id": "22222222-2222-4222-8222-222222222223", "product_id": "11111111-1111-4111-8111-111111111111" }, "response": { "data": { "duration_days": null, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/batch": { "post": { "description": "L'applicazione di una politica non modifica mai la modalità o la durata di una licenza. La creazione richiede una durata esplicita per ogni licenza a tempo limitato/di prova, indicata nella singola voce o nel campo comune del batch. Le licenze gestite da Launch rifiutano i rinnovi autonomi, singoli o in batch, con HTTP 409 LAUNCH_VALIDITY_MANAGED; rinnovare l'acquisto in Launch e sincronizzare la validità assoluta. Un batch di rinnovo misto viene annullato interamente.", "operationId": "post_api_v1_licenses_batch", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "duration_days": 30, "entries": [ { "customer": "Order #1001", "customer_email": "buyer@example.com" } ], "operation": "create", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/BatchInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "count": 1, "items": [ { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } ], "operation": "create", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BatchResult", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Operazioni in batch sulle licenze", "x-management-reference": { "group": "licenses" }, "x-request-variants": [ { "name": "create", "request": { "duration_days": 30, "entries": [ { "customer": "Order #1001", "customer_email": "buyer@example.com" } ], "operation": "create", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } ], "operation": "create", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "renew", "request": { "days": 30, "ids": [ "33333333-3333-4333-8333-333333333333" ], "operation": "renew", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "id": "33333333-3333-4333-8333-333333333333", "operation": "renew" } ], "operation": "renew", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "revoke", "request": { "ids": [ "33333333-3333-4333-8333-333333333333" ], "operation": "revoke", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "id": "33333333-3333-4333-8333-333333333333", "operation": "revoke" } ], "operation": "revoke", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "apply_policy", "request": { "ids": [ "33333333-3333-4333-8333-333333333333" ], "operation": "apply_policy", "policy_id": "22222222-2222-4222-8222-222222222222", "preview_token": "REPLACE_WITH_THE_UNEXPIRED_PREVIEW_TOKEN", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "id": "33333333-3333-4333-8333-333333333333", "operation": "apply_policy" } ], "operation": "apply_policy", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/export.csv": { "get": { "operationId": "get_api_v1_licenses_export_csv", "parameters": [ { "in": "query", "name": "product_id", "schema": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "q", "schema": { "description": "Testo di ricerca; i campi interessati e la lunghezza massima dipendono dall'operazione.", "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "description": "Stato corrente della risorsa; consultare l'enumerazione e le note dell'operazione.", "enum": [ "active", "expired", "suspended", "revoked" ], "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "example": "id,product_id,key_prefix,customer,mode,status,max_devices,expires_at\n", "schema": { "type": "string" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "413": { "content": { "application/json": { "example": { "error": { "code": "EXPORT_TOO_LARGE", "message": "Filter the export to at most 5000 records" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Filtrare fino a un massimo di 5000 record" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Esporta le licenze", "x-csv-columns": [ "id", "product_id", "key_prefix", "customer", "mode", "status", "max_devices", "expires_at" ], "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" } }, "/api/v1/licenses/policy-preview": { "post": { "description": "L'applicazione di una politica non modifica mai la modalità o la durata di una licenza. La creazione richiede una durata esplicita per ogni licenza a tempo limitato/di prova, indicata nella singola voce o nel campo comune del batch.", "operationId": "post_api_v1_licenses_policy-preview", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "ids": [ "33333333-3333-4333-8333-333333333333" ], "policy_id": "22222222-2222-4222-8222-222222222222" }, "schema": { "$ref": "#/components/schemas/PreviewInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "changes": [], "expires_in": 600, "note": "", "policy_version": 1, "preview_token": "" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicyPreview", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Mostra un'anteprima dell'applicazione della politica", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}": { "delete": { "operationId": "delete_api_v1_licenses_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Archivia una licenza", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" }, "get": { "operationId": "get_api_v1_licenses_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-18T00:00:00Z", "customer": "Order #1001", "duration_days": 30, "expires_at": null, "features": [ "export" ], "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key_prefix": "lv_lic_AAAAAAA", "max_devices": 1, "mode": "timed", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/License", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Legge una licenza", "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" }, "patch": { "operationId": "patch_api_v1_licenses_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "status": "suspended" }, "schema": { "$ref": "#/components/schemas/LicenseUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Aggiorna una licenza", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/capabilities": { "get": { "operationId": "get_api_v1_licenses_by_id_capabilities", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "customer_email": "buyer@example.com", "license": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "meter_rules": [], "usage": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseCapabilityResult", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Legge le funzionalità della licenza", "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" } }, "/api/v1/licenses/{id}/customer": { "patch": { "operationId": "patch_api_v1_licenses_by_id_customer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "email": "buyer@example.com", "name": "Sample customer" }, "schema": { "$ref": "#/components/schemas/CustomerAssignment" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Assegna un cliente", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/maintenance/renew": { "post": { "operationId": "post_api_v1_licenses_by_id_maintenance_renew", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "days": 30 }, "schema": { "$ref": "#/components/schemas/Renew" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseCapabilities", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Rinnova la manutenzione", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/renew": { "post": { "description": "Prima della prima attivazione, il rinnovo incrementa duration_days. Dopo l'attivazione, l'estensione decorre dal più recente tra l'orario corrente ed expires_at; le licenze scadute non perdono la durata dell'estensione acquistata. Le licenze gestite da Launch rifiutano i rinnovi autonomi, singoli o in batch, con HTTP 409 LAUNCH_VALIDITY_MANAGED; rinnovare l'acquisto in Launch e sincronizzare la validità assoluta. Un batch di rinnovo misto viene annullato interamente.", "operationId": "post_api_v1_licenses_by_id_renew", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "days": 30 }, "schema": { "$ref": "#/components/schemas/Renew" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "duration_days": 60, "expires_at": null, "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Renewed", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Rinnova una licenza", "x-management-reference": { "group": "licenses" }, "x-request-variants": [ { "name": "before_activation", "request": { "days": 30 }, "response": { "data": { "duration_days": 60, "expires_at": null, "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "after_activation", "request": { "days": 30 }, "response": { "data": { "duration_days": 30, "expires_at": "2026-12-17T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/reveal-key": { "post": { "description": "Requires an active Owner browser session and CSRF token. Management API keys and read-only members are forbidden. Keys are encrypted at rest and each view is audited without recording the secret. Ordinary lists, details and CSV exports contain only the prefix. Older encrypted batch/onboarding receipts are recovered during migration. Older hash-only issuances return LICENSE_KEY_UNAVAILABLE (409); Launch account licenses return LICENSE_KEY_NOT_APPLICABLE (409). Viewing does not rotate the key or change validity, devices or usage.", "operationId": "post_api_v1_licenses_by_id_reveal-key", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseKeyReveal" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "View the original license key", "x-required-role": "owner" } }, "/api/v1/licenses/{id}/revoke": { "post": { "operationId": "post_api_v1_licenses_by_id_revoke", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Revoca una licenza", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/members": { "get": { "operationId": "get_api_v1_members", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MemberList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "get /members", "x-required-role": "owner" }, "post": { "operationId": "post_api_v1_members", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Invited" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "post /members", "x-required-role": "owner" } }, "/api/v1/members/{id}": { "patch": { "operationId": "patch_api_v1_members_by_id", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "patch /members/{id}", "x-required-role": "owner" } }, "/api/v1/offline/respond": { "post": { "operationId": "post_api_v1_offline_respond", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "activation_id": "44444444-4444-4444-8444-444444444444", "app_version": "1.0.0", "created_at": 1792281600, "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "operation": "deactivate", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555", "version": 1 }, "schema": { "$ref": "#/components/schemas/OfflineRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "operation": "deactivate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OfflineResponse", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Emette una risposta offline", "x-management-reference": { "group": "integration" }, "x-request-variants": [ { "name": "activate", "request": { "app_version": "1.0.0", "created_at": 1792281600, "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "operation": "activate", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555", "version": 1 }, "response": { "data": { "operation": "activate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "device_key": "lv_dev_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "heartbeat_seconds": 600, "lease": { "key_id": "66666666-6666-4666-8666-666666666666", "payload": "BASE64URL_ENCODED_SIGNED_CLAIMS", "signature": "BASE64URL_ED25519_SIGNATURE", "version": 1 } }, "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "deactivate", "request": { "activation_id": "44444444-4444-4444-8444-444444444444", "app_version": "1.0.0", "created_at": 1792281600, "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "operation": "deactivate", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555", "version": 1 }, "response": { "data": { "operation": "deactivate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/onboarding": { "post": { "operationId": "post_api_v1_onboarding", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "duration_days": 7, "mode": "trial", "name": "Report app", "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/OnboardingInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "config": { "allow_http": false, "app_version": "1.0.0", "base_url": "https://license.example.com", "cache_path": "", "device_name": "My application", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "product_id": "11111111-1111-4111-8111-111111111111", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "license_id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "next": "Choose a language and download the configured SDK bundle.", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OnboardingResult", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Crea le risorse di integrazione", "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/payments/paddle/webhook": { "post": { "operationId": "post__api_v1_payments_paddle_webhook", "parameters": [ { "in": "header", "name": "Paddle-Signature", "required": true, "schema": { "description": "Nome visualizzato del servizio di pagamento.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleWebhookEvent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookReceived" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [], "summary": "Verifica la firma Paddle e riconcilia i pagamenti completati o le rettifiche", "x-licentivo-access": "public" } }, "/api/v1/payments/paypal/webhook": { "post": { "operationId": "post_api_v1_payments_paypal_webhook", "parameters": [ { "in": "header", "name": "Paypal-Auth-Algo", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Cert-Url", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Transmission-Id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Transmission-Sig", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Transmission-Time", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookReceived" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Notifica verificata di acquisizione/rimborso/storno" } }, "/api/v1/payments/waffo/webhook": { "post": { "operationId": "post__api_v1_payments_waffo_webhook", "parameters": [ { "in": "header", "name": "X-Waffo-Signature", "required": true, "schema": { "description": "Identificativo del commerciante che inizia con MER_.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaffoWebhookEvent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookReceived" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [], "summary": "Verifica la firma Waffo e riconcilia il pagamento o il rimborso", "x-licentivo-access": "public" } }, "/api/v1/policies": { "get": { "operationId": "get_api_v1_policies", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "product_id", "schema": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "features": [ "export" ], "heartbeat_seconds": 600, "id": "22222222-2222-4222-8222-222222222222", "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z", "version": 1 } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicyList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca le politiche", "x-management-reference": { "group": "policies" }, "x-required-scope": "read" }, "post": { "description": "Richiede una sessione Owner o una chiave di scrittura di un Owner attivo. Nessun tentativo automatico con Idempotency-Key.", "operationId": "post_api_v1_policies", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "features": [ "export" ], "heartbeat_seconds": 600, "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/PolicyCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Crea una politica", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/policies/{id}": { "delete": { "operationId": "delete_api_v1_policies_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Archivia una politica", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" }, "get": { "operationId": "get_api_v1_policies_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-18T00:00:00Z", "features": [ "export" ], "heartbeat_seconds": 600, "id": "22222222-2222-4222-8222-222222222222", "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z", "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Policy", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Legge una politica", "x-management-reference": { "group": "policies" }, "x-required-scope": "read" }, "patch": { "description": "Aggiorna in modo atomico la politica e tutte le istantanee delle licenze collegate non revocate. I termini delle licenze esistenti, gli utilizzi confermati e le estensioni di manutenzione separate vengono conservati. Restituisce synced_licenses. ACTIVE_DEVICES_CONFLICT annulla l'intero salvataggio.", "operationId": "patch_api_v1_policies_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "max_devices": 2 }, "schema": { "$ref": "#/components/schemas/PolicyUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "synced_licenses": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicySyncResult", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Aggiorna la politica di base", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/policies/{id}/capabilities": { "get": { "operationId": "get_api_v1_policies_by_id_capabilities", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "allow_vm": true, "device_match": "system", "license_model": "node_locked", "maintenance_days": 0, "max_version": "", "meter_rules": [], "min_version": "", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "require_hardware": false, "self_release_limit": 3, "session_seconds": 7200, "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicyCapabilities", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Legge le funzionalità della politica", "x-management-reference": { "group": "policies" }, "x-required-scope": "read" }, "patch": { "description": "Usare il policy_version corrente. Aggiorna in modo atomico la politica e tutte le istantanee delle licenze collegate non revocate, conservando i termini emessi, gli utilizzi confermati e le estensioni di manutenzione separate. Restituisce synced_licenses. POLICY_CHANGED o ACTIVE_DEVICES_CONFLICT annulla l'intero salvataggio.", "operationId": "patch_api_v1_policies_by_id_capabilities", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "license_model": "node_locked", "meter_rules": [ { "allow_overage": false, "feature": "export", "limit": 500, "max_overage": 0, "period": "month" } ], "policy_version": 1 }, "schema": { "$ref": "#/components/schemas/PolicyCapabilitiesInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "synced_licenses": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicySyncResult", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Aggiorna le funzionalità della politica", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products": { "get": { "operationId": "get_api_v1_products", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "q", "schema": { "description": "Testo di ricerca; i campi interessati e la lunghezza massima dipendono dall'operazione.", "maxLength": 120, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "description": "Desktop reporting software", "id": "11111111-1111-4111-8111-111111111111", "name": "Report app", "status": "active", "updated_at": "2026-10-18T00:00:00Z" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProductList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca i prodotti", "x-management-reference": { "group": "products" }, "x-required-scope": "read" }, "post": { "description": "Richiede una sessione Owner o una chiave di scrittura di un Owner attivo. Nessun tentativo automatico con Idempotency-Key.", "operationId": "post_api_v1_products", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "description": "Desktop reporting software", "name": "Report app" }, "schema": { "$ref": "#/components/schemas/ProductCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Crea prodotto", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}": { "delete": { "operationId": "delete_api_v1_products_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Archivia un prodotto", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" }, "get": { "operationId": "get_api_v1_products_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-18T00:00:00Z", "description": "Desktop reporting software", "id": "11111111-1111-4111-8111-111111111111", "name": "Report app", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Product", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Legge un prodotto", "x-management-reference": { "group": "products" }, "x-required-scope": "read" }, "patch": { "operationId": "patch_api_v1_products_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Report app Pro", "status": "active" }, "schema": { "$ref": "#/components/schemas/ProductUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Aggiorna un prodotto", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}/public-keys": { "get": { "operationId": "get_api_v1_products_by_id_public-keys", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyBundle" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Bundle di chiavi fissate per il prodotto" } }, "/api/v1/products/{id}/releases": { "get": { "operationId": "get_api_v1_products_by_id_releases", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "channel": "stable", "created_at": "2026-10-18T00:00:00Z", "download_url": "", "id": "33333333-3333-4333-8333-333333333333", "notes": "Initial release", "product_id": "11111111-1111-4111-8111-111111111111", "published_at": "2026-10-18T00:00:00Z", "sha256": "", "version": "1.0.0" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReleaseList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca le release", "x-management-reference": { "group": "releases" }, "x-required-scope": "read" }, "post": { "operationId": "post_api_v1_products_by_id_releases", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "channel": "stable", "notes": "Initial release", "version": "1.0.0" }, "schema": { "$ref": "#/components/schemas/ReleaseInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "channel": "stable", "created_at": "2026-10-18T00:00:00Z", "download_url": "", "id": "33333333-3333-4333-8333-333333333333", "notes": "Initial release", "product_id": "11111111-1111-4111-8111-111111111111", "published_at": "2026-10-18T00:00:00Z", "sha256": "", "version": "1.0.0" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Release", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Pubblica una release", "x-management-reference": { "group": "releases" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}/sdk-bundle": { "post": { "operationId": "post_api_v1_products_by_id_sdk-bundle", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "language": "go" }, "schema": { "$ref": "#/components/schemas/BundleInput" } } }, "required": true }, "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Scarica il codice sorgente di esempio del prodotto", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}/sdk-initializer": { "get": { "operationId": "get_api_v1_products_by_id_sdk-initializer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "language", "schema": { "default": "go", "description": "Identificativo del linguaggio SDK per il bundle scaricabile.", "enum": [ "go", "java", "c", "cpp", "csharp", "python", "javascript", "rust", "ruby" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "language": "go", "product_id": "11111111-1111-4111-8111-111111111111", "source": "const productID = \"11111111-1111-4111-8111-111111111111\"\nvar trustedKeys = map[string]string{\"66666666-6666-4666-8666-666666666666\": \"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"}\n", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKInitializer", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Copia il codice di inizializzazione del prodotto", "x-management-reference": { "group": "products" }, "x-required-scope": "read" } }, "/api/v1/products/{id}/signing-keys": { "get": { "operationId": "get_api_v1_products_by_id_signing-keys", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "keys": [], "product_id": "11111111-1111-4111-8111-111111111111" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ManagementKeyBundle", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca le chiavi di firma", "x-management-reference": { "group": "products" }, "x-required-scope": "read" } }, "/api/v1/products/{id}/signing-keys/rotate": { "post": { "operationId": "post_api_v1_products_by_id_signing-keys_rotate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "active": true, "algorithm": "Ed25519", "created_at": "2026-10-18T00:00:00Z", "key_id": "66666666-6666-4666-8666-666666666666", "public_key": "", "retired_at": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SigningKey", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Ruota la chiave di firma", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/releases/eligible": { "post": { "description": "Operazione di esecuzione autenticata tramite licenza; nessun cookie del fornitore o API Key. Il consumo delle funzionalità richiede un Idempotency-Key stabile; consume non comporta addebiti API della piattaforma.", "operationId": "post_api_v1_releases_eligible", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/EligibleReleases" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "/releases/eligible" } }, "/api/v1/service/status": { "get": { "description": "Solo gli avvisi globali sono pubblici; gli ID degli spazi di lavoro destinatari non vengono esposti.", "operationId": "get__api_v1_service_status", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceIncidentList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [], "summary": "Legge le manutenzioni e gli incidenti pubblici" } }, "/api/v1/sessions/logout": { "post": { "description": "Nessun cookie del browser o token CSRF. Un'operazione duplicata riproduce il risultato senza rilasciare le associazioni più recenti. Lo stato stale indica il completamento riuscito di una revoca obsoleta. Gli SDK negano l'uso locale ed eliminano le credenziali di esecuzione prima di inviare questa richiesta.", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "operation_id": "11111111-1111-4111-8111-111111111111", "product_id": "11111111-1111-4111-8111-111111111111", "release_token": "lv_out_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }, "schema": { "$ref": "#/components/schemas/LogoutTicket" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "license_id": "11111111-1111-4111-8111-111111111111", "operation_id": "11111111-1111-4111-8111-111111111111", "source": "logout", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeviceReleaseOperation", "description": "Risultato di questa operazione." }, "request_id": { "description": "Identificativo di correlazione della richiesta HTTP.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Risultato accettato" }, "400": { "description": "Input non valido" }, "401": { "description": "Autenticazione o attestazione dell'identità rifiutata" }, "403": { "description": "Diritto, credenziale, ambiente o accesso revocato" }, "409": { "description": "Conflitto di idempotenza o di versione della politica, della revisione o dell'associazione" }, "503": { "description": "Errore temporaneo; riprovare l'operazione originale" } }, "security": [], "summary": "Revoca un'associazione del dispositivo con versione usando un ticket riservato allo scollegamento", "tags": [ "Launch account licensing" ] } }, "/api/v1/summary": { "get": { "operationId": "get_api_v1_summary", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active_licenses": 0, "licenses": 0, "policies": 0, "products": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Summary", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Conteggi dello spazio di lavoro", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/support/contact": { "get": { "description": "Restituisce soltanto l'email di contatto configurata; un valore vuoto indica che è nascosta. Non viene inviata alcuna email.", "operationId": "get__api_v1_support_contact", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportContact" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [], "summary": "Legge l'indirizzo email pubblico dell'assistenza" } }, "/api/v1/system/billing-notifications": { "get": { "description": "Riutilizza il trasporto delle email di autenticazione, il mittente, la coda persistente cifrata e i tentativi successivi. Sia il permesso della piattaforma sia il consenso del destinatario devono consentire il tipo di messaggio. La consegna verifica nuovamente il consenso corrente e lo stato dell'evento. Le preferenze email non concedono né revocano il consenso agli addebiti sul portafoglio. I messaggi sandbox sono contrassegnati. Non vengono create notifiche per acquisti in sospeso non pagati o per regali.", "operationId": "get__api_v1_system_billing_notifications", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge le regole delle email di fatturazione della piattaforma", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "description": "Aggiornamento parziale; i valori esplicitamente false vengono conservati. Riutilizza il trasporto delle email di autenticazione, il mittente, la coda persistente cifrata e i tentativi successivi. Sia il permesso della piattaforma sia il consenso del destinatario devono consentire il tipo di messaggio. La consegna verifica nuovamente il consenso corrente e lo stato dell'evento. Le preferenze email non concedono né revocano il consenso agli addebiti sul portafoglio. I messaggi sandbox sono contrassegnati. Non vengono create notifiche per acquisti in sospeso non pagati o per regali.", "operationId": "patch__api_v1_system_billing_notifications", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingNotificationSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Configura le regole delle email di fatturazione e il contatto pubblico dell'assistenza", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/billing-notifications/preview": { "get": { "description": "Usa le impostazioni della piattaforma salvate e dati sandbox di esempio. Non vengono creati acquisti né attività di invio email.", "operationId": "get__api_v1_system_billing_notifications_preview", "parameters": [ { "in": "query", "name": "kind", "required": true, "schema": { "enum": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem" ], "type": "string" } }, { "in": "query", "name": "locale", "schema": { "default": "zh", "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingEmailPreview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Mostra un'anteprima di un'email di fatturazione senza inviarla", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/billing-notifications/test": { "post": { "description": "Il test esplicito usa dati sandbox di esempio, aggiunge [TEST] e segue la configurazione email esistente. Può verificare un modello anche se quel tipo di notifica al cliente è disabilitato. Non vengono eseguiti pagamenti né rinnovi.", "operationId": "post__api_v1_system_billing_notifications_test", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEmailTestInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailQueued" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Accoda un'email di fatturazione di test richiesta", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/check-mail": { "post": { "description": "Verifica soltanto il servizio salvato. Le verifiche dei fornitori API usano richieste di sola lettura e non inviano mai email. Una chiave abilitata soltanto all'invio può produrre check_status=limited e ok=false; ciò non conferma la validità delle credenziali né la riuscita della consegna. Per verificare l'invio è necessaria una richiesta esplicita di email di test.", "operationId": "post_api_v1_system_check-mail", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailConnection" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "MAIL_PROVIDER_AUTH_FAILED, MAIL_PROVIDER_RATE_LIMITED o MAIL_PROVIDER_UNAVAILABLE. L'invio dell'email di test è asincrono; gli errori di consegna compaiono nell'esito dell'attività anziché nella risposta HTTP 202 originale." } }, "security": [ { "session": [] } ], "summary": "post /system/check-mail", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases": { "get": { "description": "", "operationId": "get__api_v1_system_customer_cases", "parameters": [ { "description": "Esclude un tipo di richiesta prima del conteggio e della paginazione. Usare refund per escludere i casi di rimborso dall'elenco dell'assistenza; l'accesso rimane limitato alla sessione corrente.", "in": "query", "name": "exclude_kind", "schema": { "maxLength": 24, "type": "string" } }, { "description": "Limita i casi di rimborso alle ricariche del portafoglio o all'annullamento del servizio.", "in": "query", "name": "refund_scope", "required": false, "schema": { "enum": [ "wallet", "service" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Elenca le richieste dei clienti", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/unread": { "get": { "description": "Le chat sui rimborsi sono escluse. I clienti vedono soltanto i ticket autorizzati dello spazio di lavoro; i membri vedono i propri. Ogni amministratore ha un indicatore di lettura indipendente.", "operationId": "get__api_v1_system_customer_cases_unread", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportUnread" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge i conteggi personali dei ticket e degli avvisi non letti", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}": { "get": { "description": "", "operationId": "get__api_v1_system_customer_cases__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge una richiesta e le risposte", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/deletion-review": { "post": { "description": "Richiede il riconoscimento delle responsabilità finanziarie. Revoca immediatamente l'accesso normale; chiude l'esportazione del cliente allo scadere esatto di 30 giorni e conserva tutti i record applicativi per l'esportazione autorizzata da parte degli amministratori.", "operationId": "post__api_v1_system_customer_cases__id__deletion_review", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountClosureReview" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Conferma o respinge la chiusura logica dell'account", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/manual-refund": { "post": { "description": "Richiede l'accordo del cliente e la prova del pagamento completato. Registra il regolamento; non invia mai un bonifico bancario. Una conferma ripetuta non può addebitare due volte. I pagamenti originali Waffo/Paddle, inclusi quelli per servizi, rifiutano questo percorso basato sulla sola dichiarazione con ORIGINAL_REFUND_REQUIRED.", "operationId": "post__api_v1_system_customer_cases__id__manual_refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualRefundInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Registra un rimborso alternativo effettivamente completato", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/messages": { "post": { "description": "I casi di rimborso rifiutano le risposte con REFUND_REVIEW_WORKFLOW; gli amministratori approvano o respingono direttamente. I normali ticket di assistenza conservano le risposte. Le chiusure già esaminate mantengono il proprio stato nella procedura di privacy.", "operationId": "post__api_v1_system_customer_cases__id__messages", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReply" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Risponde a un ticket di assistenza", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/read": { "post": { "description": "Vengono contrassegnati come letti soltanto i messaggi fino all'ultimo visualizzato. Quelli arrivati successivamente rimangono non letti e le conferme ritardate non possono far arretrare l'indicatore di lettura.", "operationId": "post__api_v1_system_customer_cases__id__read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReadInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Conferma la lettura dei messaggi del ticket visualizzati", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/recover-original-refund": { "post": { "description": "Richiede la conferma esplicita dell'amministratore che non sia stato effettivamente eseguito alcun trasferimento alternativo. Conserva le prove originali e usa registrazioni contabili compensative. Viene richiesto ai pagamenti originali soltanto l'importo rimanente.", "operationId": "post__api_v1_system_customer_cases__id__recover_original_refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoverOriginalRefund" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" } }, "security": [ { "session": [] } ], "summary": "Corregge una dichiarazione manuale non pagata e richiede il rimborso originale", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/refund-quote": { "post": { "description": "Nuova anteprima dell'ambito, dell'importo e della pianificazione. Una modifica dell'ambito del servizio richiede una nuova domanda del cliente; l'amministratore può respingere direttamente quella precedente.", "operationId": "post__api_v1_system_customer_cases__id__refund_quote", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRefundPreviewInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ScopedRefundPreview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Mostra un'anteprima di una domanda con ambito definito in sospeso prima dell'approvazione", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/refund-review": { "post": { "description": "Serializza le operazioni sullo spazio di lavoro di destinazione. L'approvazione riserva i fondi disponibili del portafoglio, assegna i rimborsi sul metodo originale usando ID di richiesta stabili del fornitore e conserva l'eventuale saldo che richiede un'alternativa concordata. Le approvazioni Waffo/Paddle creano intenzioni di rimborso persistenti presso il fornitore originale e inviano richieste alle API di rimborso del commerciante. Nessuna dichiarazione manuale può completare questi rimborsi. Uno stato di approvazione processing/pending non indica fondi regolati.", "operationId": "post__api_v1_system_customer_cases__id__refund_review", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundReview" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Approva o respinge il rimborso del cliente", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/legal/policy": { "get": { "description": "", "operationId": "get__api_v1_system_legal_policy", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommercePolicy" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge il profilo dell'operatore e le versioni delle politiche in attesa", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "description": "La pubblicazione richiede una denominazione legale dell'operatore confermata e un indirizzo email di contatto valido. Gli altri dati del profilo sono facoltativi e quelli non confermati vengono omessi dai documenti pubblici. Le sostituzioni pubblicate mantengono la versione precedente durante un preavviso di almeno 30 giorni tramite console ed email inviate con successo.", "operationId": "patch__api_v1_system_legal_policy", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercePolicyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommercePolicy" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Pubblica o programma le politiche di servizio", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/mail-jobs": { "get": { "description": "Solo sessioni di amministratori della piattaforma. Gli ultimi 50 messaggi con tipo, ambiente, destinatario, tentativi, stato e motivo di annullamento. I payload dei messaggi consegnati/annullati vengono cancellati. L'accettazione SMTP non equivale alla consegna nella casella di posta né alla lettura.", "operationId": "get_api_v1_system_mail-jobs", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailJobList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "get /system/mail-jobs", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/mail-jobs/{id}/retry": { "post": { "description": "Azzera il numero di tentativi e accoda lo stesso messaggio fallito. Le attività consegnate, annullate, in esecuzione e in sospeso restituiscono MAIL_JOB_NOT_RETRYABLE. Prima del nuovo tentativo di consegna, le attività di fatturazione verificano nuovamente il consenso corrente e lo stato dell'evento. Gli errori SMTP non annullano mai un pagamento confermato.", "operationId": "post__api_v1_system_mail_jobs__id__retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailQueued" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Riprova un'email fallita il cui payload cifrato è stato conservato", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/operations": { "get": { "description": "Solo sessioni di amministratori della piattaforma. Log applicativo di sola aggiunta con autore, soggetto, motivo e modifiche esplicite.", "operationId": "get__api_v1_system_operations", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "user_id", "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "action", "schema": { "maxLength": 80, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformOperationList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Elenca le operazioni amministrative sui clienti" } }, "/api/v1/system/overview": { "get": { "description": "Solo sessioni di amministratori della piattaforma. Le metriche dei pacchetti usano l'ambiente di pagamento attualmente configurato. I nuovi utenti coprono gli ultimi 30 giorni; le scadenze coprono i prossimi 7 giorni.", "operationId": "get__api_v1_system_overview", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformOverview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge i totali dei clienti e dei pacchetti della piattaforma" } }, "/api/v1/system/paddle": { "get": { "operationId": "get__api_v1_system_paddle", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleSettings" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge la configurazione Paddle senza chiavi private", "x-licentivo-access": "platform" }, "patch": { "operationId": "patch__api_v1_system_paddle", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleSettings" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Salva le credenziali Paddle Billing cifrate", "x-licentivo-access": "platform" } }, "/api/v1/system/paddle/check": { "post": { "operationId": "post__api_v1_system_paddle_check", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleCheck" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Verifica le credenziali Paddle e il prodotto attivo", "x-licentivo-access": "platform" } }, "/api/v1/system/paddle/orders": { "get": { "operationId": "get__api_v1_system_paddle_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderList" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Elenca i pagamenti di servizi e le ricariche del portafoglio Paddle", "x-licentivo-access": "platform" } }, "/api/v1/system/paddle/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_system_paddle_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleReconcileInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Riconcilia o recupera una transazione originale senza creare un addebito", "x-licentivo-access": "platform" } }, "/api/v1/system/payment-channels": { "get": { "operationId": "get__api_v1_system_payment_channels", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaymentChannels" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Elenca i canali di pagamento configurabili separatamente", "x-licentivo-access": "platform" }, "patch": { "operationId": "patch__api_v1_system_payment_channels", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentChannelInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaymentChannels" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Abilita o disabilita atomicamente i canali con controllo ottimistico della concorrenza", "x-licentivo-access": "platform" } }, "/api/v1/system/paypal": { "get": { "operationId": "get_api_v1_system_paypal", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "PayPal", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "operationId": "patch_api_v1_system_paypal", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayPalInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "PayPal", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/check": { "post": { "operationId": "post_api_v1_system_paypal_check", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalCheck" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Verifica PayPal", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/orders/{id}/refund": { "post": { "description": "Solo sessioni di amministratori della piattaforma. Riserva il credito disponibile e non speso del portafoglio prima di contattare PayPal. Pending indica che il risultato non è confermato; riconciliare la stessa richiesta. Non annulla automaticamente un pacchetto.", "operationId": "post__api_v1_system_paypal_orders__id__refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalRefund" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." } }, "security": [ { "session": [] } ], "summary": "Rimborsa i fondi inutilizzati del portafoglio tramite il metodo di pagamento PayPal originale" } }, "/api/v1/system/paypal/refund-requests": { "get": { "description": "Solo sessioni tramite cookie; le chiavi API amministrative non sono accettate. Le letture dei clienti sono limitate al proprio spazio di lavoro. Le scritture dei clienti richiedono un Owner verificato dello spazio di lavoro, senza necessità del permesso di amministratore della piattaforma. Le domande non spostano né riservano fondi. L'approvazione dell'amministratore verifica nuovamente il portafoglio corrente e il valore acquisito non ancora rimborsato, quindi usa la procedura idempotente esistente di rimborso sul metodo originale e prenotazione. L'approvazione non annulla i piani.", "operationId": "get__api_v1_system_paypal_refund_requests", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequestList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" } }, "security": [ { "session": [] } ], "summary": "Elenca le domande di rimborso dei clienti da esaminare", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/refund-requests/{id}/review": { "post": { "description": "Solo sessioni tramite cookie; le chiavi API amministrative non sono accettate. Le letture dei clienti sono limitate al proprio spazio di lavoro. Le scritture dei clienti richiedono un Owner verificato dello spazio di lavoro, senza necessità del permesso di amministratore della piattaforma. Le domande non spostano né riservano fondi. L'approvazione dell'amministratore verifica nuovamente il portafoglio corrente e il valore acquisito non ancora rimborsato, quindi usa la procedura idempotente esistente di rimborso sul metodo originale e prenotazione. L'approvazione non annulla i piani.", "operationId": "post__api_v1_system_paypal_refund_requests__id__review", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRefundReview" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequest" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, autenticazione, titolarità, conflitto di revisione o saldo" } }, "security": [ { "session": [] } ], "summary": "Approva o respinge una domanda di rimborso del cliente", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/refunds": { "get": { "description": "Solo sessioni di amministratori della piattaforma.", "operationId": "get__api_v1_system_paypal_refunds", "parameters": [ { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RefundList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." } }, "security": [ { "session": [] } ], "summary": "Elenca le richieste di rimborso per l'ambiente di pagamento selezionato" } }, "/api/v1/system/paypal/refunds/{id}/reconcile": { "post": { "description": "Solo sessioni di amministratori della piattaforma. Riprova con lo stesso PayPal-Request-Id se l'ID del rimborso non è stato ricevuto, oppure recupera il rimborso già esistente presso il fornitore.", "operationId": "post__api_v1_system_paypal_refunds__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalRefund" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." } }, "security": [ { "session": [] } ], "summary": "Riconcilia lo stesso rimborso senza una nuova identità di addebito" } }, "/api/v1/system/plan-gifts": { "get": { "description": "Solo sessioni di amministratori della piattaforma. Il destinatario indicato rappresenta lo spazio di lavoro deduplicato. La ricerca trova corrispondenze nell'email del destinatario, nello spazio di lavoro o nel nome del pacchetto.", "operationId": "get__api_v1_system_plan_gifts", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "user_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Elenca la cronologia dei regali" }, "post": { "description": "Solo sessioni di amministratori della piattaforma. Batch atomico. Fornire fingerprint dall'anteprima e un request_id stabile; una ripetizione corrispondente restituisce lo stesso batch. Le modifiche al livello o alla pianificazione richiedono una nuova anteprima. I regali mantengono un pagamento effettivo pari a zero e non possono diventare rimborsi in denaro. Il valore del beneficio acquisito viene accreditato normalmente durante un upgrade. Soltanto i nuovi regali dello stesso livello corrente non ancora iniziati seguono un upgrade successivo senza ulteriori pagamenti, conservando le proprie date. I regali storici non vengono mai riallineati; le quote mensili e le regole sugli sforamenti si applicano normalmente. I batch misti usano i metadati current/---; per ogni livello e valuta effettivi, esaminare i singoli record dei regali associati agli acquisti.", "operationId": "post__api_v1_system_plan_gifts", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGiftInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Conferma un regalo dello stesso livello corrente dopo la revisione" } }, "/api/v1/system/plan-gifts/preview": { "post": { "description": "Solo sessioni di amministratori della piattaforma. Da 1 a 100 ID utente distinti di clienti attivi. Gli utenti dello stesso spazio di lavoro ricevono un solo contratto. Ogni voce eredita il pacchetto attualmente valido del cliente oppure l'ultimo pacchetto scaduto nell'ambiente selezionato. I batch con livelli misti restituiscono il piano e il valore del beneficio effettivi per ogni voce. Omettere plan/currency/price_version; gli eventuali valori espliciti devono corrispondere al pacchetto esistente di ogni cliente. I clienti privi di un pacchetto non possono ricevere un livello diverso tramite questo endpoint. after_current aggiunge il regalo dopo tutta la copertura pagata/regalata; immediate rifiuta diritti sovrapposti. Nessuna scrittura o addebito.", "operationId": "post__api_v1_system_plan_gifts_preview", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGiftPreviewInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftPreview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Mostra un'anteprima di un pacchetto regalo dello stesso livello corrente" } }, "/api/v1/system/plan-gifts/{id}/cancel": { "post": { "description": "Solo sessioni di amministratori della piattaforma. L'annullamento ripetuto è sicuro. Interrompe questo contratto senza eliminare la cronologia, rimborsare gli sforamenti o spostare altri contratti programmati.", "operationId": "post__api_v1_system_plan_gifts__id__cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformReason" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftCancellation" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Annulla un regalo attivo o programmato" } }, "/api/v1/system/plans": { "get": { "operationId": "get_api_v1_system_plans", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AdminPlanList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Piani", "x-platform-admin": true, "x-required-role": "owner" }, "post": { "operationId": "post_api_v1_system_plans", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Price" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Piani", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/plans/customer-controls": { "patch": { "description": "Solo sessioni di amministratori della piattaforma. Entrambi gli interruttori hanno valore predefinito false. Fornire device_enabled, api_enabled o entrambi. Gli interruttori omessi mantengono lo stato corrente. Ogni interruttore disabilitato nasconde i relativi controlli del cliente e ignora soltanto la propria preferenza salvata fino alla riattivazione. Le quote API contrassegnate come illimitate rimangono illimitate.", "operationId": "patch__api_v1_system_plans_customer_controls", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerControlsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerControlsResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Consente separatamente le impostazioni del cliente sugli sforamenti dei dispositivi o delle API" } }, "/api/v1/system/plans/default": { "patch": { "operationId": "patch_api_v1_system_plans_default", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefaultPlan" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DefaultPlan" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Piano predefinito", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/privacy/retention": { "get": { "description": "", "operationId": "get__api_v1_system_privacy_retention", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge le esecuzioni di archiviazione e conservazione", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/privacy/retention/run": { "post": { "description": "Solo archiviazione logica; le righe dei clienti e dei dati applicativi vengono conservate. Esegue la rotazione dei file di backup gestiti .lvb autenticati dopo 90 giorni e dei log di sicurezza dell'applicazione dopo sei mesi solari. Le esecuzioni vengono serializzate tramite un blocco del database.", "operationId": "post__api_v1_system_privacy_retention_run", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Confirmation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Elabora le archiviazioni e le conservazioni già dovute", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/provider-refunds/{id}/reconcile": { "post": { "description": "Consulta la richiesta esistente tramite il relativo riferimento del fornitore/applicativo. Soltanto un'intenzione persistente non ancora inviata può emettere la sua prima richiesta; gli invii duplicati o dall'esito sconosciuto non vengono mai ripetuti. Il completamento richiede ricevute del fornitore originale verificate indipendentemente.", "operationId": "post__api_v1_system_provider_refunds__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProviderRefund" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" } }, "security": [ { "session": [] } ], "summary": "Riconcilia il rimborso esistente sul canale originale", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/refund-requests": { "get": { "description": "Sessione di amministratore della piattaforma in sola lettura. Combina le domande di rimborso del portafoglio e i casi di annullamento di portafogli/servizi dei fornitori. I conteggi in sospeso per ambiente sono indipendenti dai filtri di paginazione e ambito. La lettura non approva, blocca né rimborsa mai fondi; usare l'endpoint di revisione esistente di ciascuna origine.", "operationId": "get_system_refund_requests", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "review", "schema": { "enum": [ "pending", "all" ], "type": "string" } }, { "in": "query", "name": "scope", "schema": { "enum": [ "wallet", "service" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RefundInboxList" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Richieste e conteggi delle revisioni in sospeso per ambiente" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, sessione o permessi" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, sessione o permessi" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, sessione o permessi" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, sessione o permessi" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, sessione o permessi" } }, "security": [ { "session": [] } ], "summary": "Coda unificata di revisione dei rimborsi dei clienti", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/refunds": { "get": { "operationId": "get__api_v1_system_refunds", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RefundHistory" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" } }, "security": [ { "session": [] } ], "summary": "Elenca i rimborsi PayPal, Waffo e Paddle", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/revenue": { "get": { "operationId": "get_api_v1_system_revenue", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "month", "schema": { "description": "all oppure UTC YYYY-MM", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Revenue" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Ricavi", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/sdk-example": { "post": { "description": "Solo sessioni Owner di amministratori della piattaforma, con CSRF. Le chiavi API vengono rifiutate. Riutilizza il prodotto e la politica dedicati; non rinnova le prove esistenti.", "operationId": "post_api_v1_system_sdk-example", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SDKExampleSetup" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKExampleSetting" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "Prepara/abilita il prodotto dedicato dell'amministratore per gli esempi SDK pubblici", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/service/incidents": { "get": { "description": "", "operationId": "get__api_v1_system_service_incidents", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceIncidentList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge tutti gli avvisi di servizio", "x-platform-admin": true, "x-required-role": "owner" }, "post": { "description": "La manutenzione non urgente richiede un preavviso di almeno 24 ore. Un incidente continuo verificato che supera le 24 ore accredita il tempo pagato effettivamente interessato; gli intervalli sovrapposti non vengono compensati due volte. Oltre sette giorni può sussistere il diritto al rimborso del servizio inutilizzato.", "operationId": "post__api_v1_system_service_incidents", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceIncidentInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceIncident" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Pubblica una manutenzione o risolve un incidente", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/settings": { "get": { "operationId": "get_api_v1_system_settings", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SystemSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "get /system/settings", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "operationId": "patch_api_v1_system_settings", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "patch /system/settings", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/test-mail": { "post": { "description": "Accoda esplicitamente un messaggio di test reale al destinatario indicato, usando il servizio di consegna salvato. HTTP 202 conferma l'accettazione nella coda, non l'arrivo nella casella di posta. Seguire lo stato dell'attività e controllare il pannello del fornitore/la casella di posta per i problemi di consegna.", "operationId": "post_api_v1_system_test-mail", "parameters": [ { "description": "Obbligatorio per le scritture con autenticazione tramite cookie o pubblica; esente soltanto per le scritture sulle risorse con Bearer supportate", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestMail" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailQueued" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] } ], "summary": "post /system/test-mail", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/tls": { "get": { "description": "Solo sessioni browser di amministratori della piattaforma. Le chiavi API amministrative e i proprietari dei tenant vengono rifiutati. Rispecchia il certificato usato da questo processo. Non espone il PEM del certificato né la chiave privata.", "operationId": "get__api_v1_system_tls", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TLSStatus" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo; vengono restituiti soltanto i metadati pubblici del certificato." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." } }, "security": [ { "session": [] } ], "summary": "Legge il certificato HTTPS attivo" }, "patch": { "description": "Solo sessioni browser di amministratori della piattaforma. Le chiavi API amministrative e i proprietari dei tenant vengono rifiutati. Convalida e cifra il certificato/la chiave in MySQL, registra un evento di controllo, quindi sostituisce il certificato attivo. I nuovi handshake TLS lo usano immediatamente; le connessioni esistenti proseguono normalmente. Dopo un riavvio, il certificato del database ha la precedenza sui file di avvio iniziale.", "operationId": "patch__api_v1_system_tls", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TLSCertificateUpdateInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TLSCertificateResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo; vengono restituiti soltanto i metadati pubblici del certificato." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." } }, "security": [ { "session": [] } ], "summary": "Sostituisce immediatamente il certificato HTTPS" } }, "/api/v1/system/tls/check": { "post": { "description": "Solo sessioni browser di amministratori della piattaforma. Le chiavi API amministrative e i proprietari dei tenant vengono rifiutati. Verifica formato, robustezza della chiave, corrispondenza della chiave, nome host, validità e catena di fiducia. HTTPS diretto deve essere abilitato. Il certificato attivo rimane invariato.", "operationId": "post__api_v1_system_tls_check", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TLSCertificateInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TLSCertificateInfo" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo; vengono restituiti soltanto i metadati pubblici del certificato." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED e TLS_SETTINGS_CONFLICT mantengono il certificato precedente." } }, "security": [ { "session": [] } ], "summary": "Convalida un certificato e una chiave privata senza salvarli" } }, "/api/v1/system/translation": { "get": { "description": "Solo sessioni di amministratori della piattaforma.", "operationId": "get__api_v1_system_translation", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." } }, "security": [ { "session": [] } ], "summary": "Legge le impostazioni DeepL senza esporre la chiave API" }, "patch": { "description": "Solo sessioni di amministratori della piattaforma. Usare expected_version dall'ultima richiesta GET. La chiave non viene mai restituita.", "operationId": "patch__api_v1_system_translation", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." } }, "security": [ { "session": [] } ], "summary": "Salva le impostazioni DeepL cifrate" } }, "/api/v1/system/translation/check": { "post": { "description": "Chiama soltanto gli endpoint DeepL per le lingue e l'utilizzo; non viene inviato alcun contenuto del forum.", "operationId": "post__api_v1_system_translation_check", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationCheck" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare error.code ed error.message; request_id identifica la richiesta." } }, "security": [ { "session": [] } ], "summary": "Verifica la chiave API salvata e recupera le lingue supportate e l'utilizzo" } }, "/api/v1/system/users": { "get": { "description": "Solo sessioni di amministratori della piattaforma. Include gli account non verificati e i membri dei team; non restituisce mai hash o token di autenticazione.", "operationId": "get__api_v1_system_users", "parameters": [ { "description": "Corrispondenza parziale di email, nome o spazio di lavoro senza distinzione tra maiuscole e minuscole; i caratteri jolly vengono sottoposti a escape.", "in": "query", "name": "q", "schema": { "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "enum": [ "active", "disabled" ], "type": "string" } }, { "in": "query", "name": "role", "schema": { "enum": [ "owner", "read_only" ], "type": "string" } }, { "in": "query", "name": "verified", "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformUserList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Elenca tutti gli utenti registrati" } }, "/api/v1/system/users/export.csv": { "get": { "description": "Solo sessioni di amministratori della piattaforma. Massimo 10000 record corrispondenti, UTF-8 con BOM ed escape delle formule dei fogli di calcolo. Nessuna credenziale.", "operationId": "get__api_v1_system_users_export_csv", "parameters": [ { "description": "Corrispondenza parziale di email, nome o spazio di lavoro senza distinzione tra maiuscole e minuscole; i caratteri jolly vengono sottoposti a escape.", "in": "query", "name": "q", "schema": { "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "enum": [ "active", "disabled" ], "type": "string" } }, { "in": "query", "name": "role", "schema": { "enum": [ "owner", "read_only" ], "type": "string" } }, { "in": "query", "name": "verified", "schema": { "enum": [ "true", "false" ], "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "Allegato CSV" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Esporta in CSV gli utenti registrati filtrati" } }, "/api/v1/system/users/{id}": { "get": { "description": "Solo sessioni di amministratori della piattaforma. I saldi dello spazio di lavoro, gli ultimi 20 contratti e i totali cumulativi pagati/rimborsati tramite PayPal sono separati per valuta e ambiente.", "operationId": "get__api_v1_system_users__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformUserDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge i dettagli del cliente e dello spazio di lavoro" }, "patch": { "description": "Solo sessioni di amministratori della piattaforma. Richiede un motivo dell'operazione e una versione per il controllo ottimistico della concorrenza. La disabilitazione revoca le sessioni, le chiavi e i link di accesso esistenti. Il ripristino non ripristina le chiavi. Gli account degli amministratori della piattaforma sono protetti.", "operationId": "patch__api_v1_system_users__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformUserUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformUserDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Aggiorna lo stato del cliente o una nota amministrativa privata" } }, "/api/v1/system/users/{id}/data-export": { "post": { "description": "Disponibile dopo la chiusura dell'account e dopo il termine concesso al cliente. Richiede la password dell'amministratore, l'ambito e un motivo operativo registrato per il controllo. Nessun record applicativo viene cancellato.", "operationId": "post__api_v1_system_users__id__data_export", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDataExportInput" } } }, "required": true }, "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Esporta i record dei clienti conservati", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/users/{id}/revoke-credentials": { "post": { "description": "Solo sessioni di amministratori della piattaforma. Non disabilita l'account; il cliente può accedere nuovamente. Le credenziali degli amministratori non possono essere revocate qui.", "operationId": "post__api_v1_system_users__id__revoke_credentials", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformReason" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformRevocation" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Revoca le sessioni e le chiavi API esistenti del cliente" } }, "/api/v1/system/waffo": { "get": { "operationId": "get__api_v1_system_waffo", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoSettings" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Legge le impostazioni Waffo senza la chiave di firma", "x-licentivo-access": "platform" }, "patch": { "operationId": "patch__api_v1_system_waffo", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaffoSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoSettings" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Salva le credenziali Waffo cifrate", "x-licentivo-access": "platform" } }, "/api/v1/system/waffo/check": { "post": { "operationId": "post__api_v1_system_waffo_check", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoCheck" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Verifica le credenziali Waffo e il prodotto attivo con pagamento una tantum", "x-licentivo-access": "platform" } }, "/api/v1/system/waffo/orders": { "get": { "operationId": "get__api_v1_system_waffo_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderList" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Elenca i pagamenti di servizi e le ricariche del portafoglio Waffo", "x-licentivo-access": "platform" } }, "/api/v1/system/waffo/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_system_waffo_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "Identificativo locale del pagamento del servizio.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Recupera e riconcilia il pagamento Waffo originale", "x-licentivo-access": "platform" } }, "/api/v1/system/workspaces/{id}/status": { "patch": { "description": "Solo sessioni di amministratori della piattaforma. La sospensione blocca l'accesso, le API amministrative e la concessione di licenze online e revoca le credenziali. Il termine dei contratti continua a decorrere. Gli spazi di lavoro della piattaforma sono protetti; le cache offline firmate restano soggette alla propria scadenza esistente.", "operationId": "patch__api_v1_system_workspaces__id__status", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformWorkspaceUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformWorkspaceStatus" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Esaminare error.code ed error.message." } }, "security": [ { "session": [] } ], "summary": "Sospende o ripristina l'intero spazio di lavoro di un cliente" } }, "/api/v1/system/{provider}/orders/{id}/refund": { "post": { "description": "Sessione di amministratore della piattaforma. Per un servizio pagato occorre invece l'annullamento. Un pagamento non applicato viene rimborsato senza movimenti del portafoglio. Un request_id stabile salva l'intenzione in modo persistente prima della chiamata al gateway; gli esiti sconosciuti vengono consultati e le richieste non vengono mai reinviate alla cieca.", "operationId": "post__api_v1_system__provider__orders__id__refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "waffo", "paddle" ], "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginalRefundInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OriginalRefundResult" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Errore di convalida, titolarità, ambiente, stato del rimborso o fornitore" } }, "security": [ { "session": [] } ], "summary": "Avvia un rimborso sul canale originale per credito non speso o un pagamento non applicato", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/usage": { "get": { "description": "Il mese corrente mostra le registrazioni dei dispositivi attivi; i mesi precedenti mostrano la cronologia registrata degli utilizzi dei dispositivi. Le quote API dei pacchetti acquistati seguono i propri mesi della quota. La cronologia dei dispositivi viene conservata dopo il rilascio. L'occupazione corrente e i picchi di fatturazione sono misure distinte.", "operationId": "get_api_v1_usage", "parameters": [ { "description": "Mese solare UTC; il valore predefinito è quello corrente", "in": "query", "name": "month", "schema": { "description": "Mese UTC YYYY-MM; i valori di query omessi usano il mese corrente. Le attività di fatturazione richiedono un mese concluso.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active_devices": 0, "api_calls": 0, "api_period": null, "billable_devices": 0, "estimated_total_cents": 0, "estimated_total_micros": 0, "month": "2026-09", "operations": [], "overage_devices": 0, "period": null, "products": [], "purchased": null, "purchased_active_devices": 0, "sandbox": false, "timezone": "UTC", "warning": "normal" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Usage", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "La quota predefinita è disabilitata (DEFAULT_PLAN_DISABLED)" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Current device occupancy, historical device use and metered API usage", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/usage/devices": { "get": { "description": "Record di utilizzo dei dispositivi per il mese UTC selezionato, conservati dopo il rilascio del dispositivo. È una cronologia delle attività, non un elenco dei dispositivi attualmente online. Per l'occupazione corrente usare GET /api/v1/usage.", "operationId": "get_api_v1_usage_devices", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "description": "Mese solare UTC; il valore predefinito è quello corrente", "in": "query", "name": "month", "schema": { "description": "Mese UTC YYYY-MM; i valori di query omessi usano il mese corrente. Le attività di fatturazione richiedono un mese concluso.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, { "in": "query", "name": "product_id", "schema": { "description": "UUID del prodotto nello spazio di lavoro corrente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "first_seen_at": "2026-09-01T00:00:00Z", "last_seen_at": "2026-09-30T00:00:00Z", "month": "2026-09", "product_id": "11111111-1111-4111-8111-111111111111" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/UsageDeviceList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca i dispositivi utilizzati", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/usage/export.csv": { "get": { "description": "Record di utilizzo dei dispositivi per il mese UTC selezionato, conservati dopo il rilascio del dispositivo. È una cronologia delle attività, non un elenco dei dispositivi attualmente online. Per l'occupazione corrente usare GET /api/v1/usage.", "operationId": "get_api_v1_usage_export_csv", "parameters": [ { "description": "Mese solare UTC; il valore predefinito è quello corrente", "in": "query", "name": "month", "schema": { "description": "Mese UTC YYYY-MM; i valori di query omessi usano il mese corrente. Le attività di fatturazione richiedono un mese concluso.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "example": "month,product_id,device_id,first_seen_utc,last_seen_utc\n", "schema": { "type": "string" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Esporta l'utilizzo", "x-csv-columns": [ "month", "product_id", "device_id", "first_seen_utc", "last_seen_utc" ], "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/validate": { "post": { "description": "Autenticazione tramite product_id + license_key + device_id. Nessun cookie/CSRF/chiave del fornitore. activation_id è obbligatorio tranne che per activate. Ogni richiesta riuscita consuma una chiamata API; le ripetizioni idempotenti e gli errori non consumano chiamate. Gli sforamenti addebitano il portafoglio in modo atomico oppure restituiscono API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT. Le ricevute dei tentativi successivi di convalida e heartbeat scadono dopo 3600 secondi. Finché l'autorizzazione originale rimane valida, le richieste corrispondenti entro questa finestra riproducono il risultato senza un ulteriore addebito. Dopo la finestra usare una nuova chiave; una chiave già usata può essere elaborata come una nuova richiesta. Le ricevute di attivazione, disattivazione e utilizzo delle funzionalità rimangono persistenti. La quota dei dispositivi dello spazio di lavoro segue le attivazioni correnti. Il rilascio restituisce capacità; anche la scadenza di un lease flottante restituisce capacità, mentre una registrazione ordinaria offline continua a essere conteggiata. Gli sforamenti dei dispositivi vengono addebitati soltanto quando il picco di fatturazione del mese della quota supera la capacità già pagata; il rilascio non rimborsa i costi già sostenuti. L'utilizzo delle API è separato.", "operationId": "post_api_v1_validate", "parameters": [ { "description": "Generare una nuova chiave per ogni operazione; i tentativi successivi conservano la stessa chiave e lo stesso corpo. Massimo 80 caratteri, senza spazi bianchi. Facoltativa per la convalida e l'heartbeat.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Convalida in fase di esecuzione" } }, "/api/v1/webhook-deliveries/{id}/attempts": { "get": { "operationId": "get_api_v1_webhook-deliveries_by_id_attempts", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AttemptList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca i tentativi di consegna", "x-management-reference": { "group": "webhooks" }, "x-required-scope": "read" } }, "/api/v1/webhook-deliveries/{id}/retry": { "post": { "operationId": "post_api_v1_webhook-deliveries_by_id_retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Riprova la consegna di un webhook", "x-management-reference": { "group": "webhooks" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/webhooks": { "get": { "operationId": "get_api_v1_webhooks", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "event_types": [], "items": [ { "created_at": "2026-10-18T00:00:00Z", "enabled": true, "events": [], "id": "33333333-3333-4333-8333-333333333333", "name": "Report app", "updated_at": "2026-10-18T00:00:00Z", "url": "https://merchant.example.com/license-events" } ] }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicensingWebhookList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca i webhook", "x-management-reference": { "group": "webhooks" }, "x-required-scope": "read" }, "post": { "operationId": "post_api_v1_webhooks", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "enabled": true, "events": [ "license.created", "license.renewed" ], "name": "Order system", "url": "https://merchant.example.com/license-events" }, "schema": { "$ref": "#/components/schemas/LicensingWebhookInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "secret": "whsec_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicensingWebhookSecret", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Salva un webhook", "x-management-reference": { "group": "webhooks" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/webhooks/{id}/deliveries": { "get": { "operationId": "get_api_v1_webhooks_by_id_deliveries", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "ID univoco di questa risorsa; usare nel percorso l'ID della risorsa corrispondente.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Dimensione della pagina, valore predefinito 25, intervallo 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Record da saltare, valore predefinito 0, intervallo 0–100000; aggiungere limit per la pagina successiva.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": null, "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeliveryList", "description": "Risultato applicativo in caso di successo; in caso di errore viene usato error." }, "request_id": { "description": "UUID di tracciamento HTTP al livello principale. Nell'input delle operazioni in batch/di configurazione iniziale è un UUID di idempotenza generato dal chiamante; i due identificativi hanno scopi diversi.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Elenca le consegne dei webhook", "x-management-reference": { "group": "webhooks" }, "x-required-scope": "read" } }, "/healthz": { "get": { "operationId": "get_healthz", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Health" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" } }, "security": [], "summary": "Operatività del processo" } }, "/readyz": { "get": { "operationId": "get_readyz", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Health" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successo" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Consultare docs/error-codes.md per l'applicabilità ai singoli endpoint" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Database non disponibile" } }, "security": [], "summary": "Disponibilità del database" } } }, "servers": [ { "url": "https://www.licentivo.com" } ] }