Per sviluppatori

Verificatoverificato 2026-09-20

In breve

MitoOps ha un’interfaccia pubblica con tre forme sopra lo stesso livello di dati normalizzato. Si differenziano per chi chiede e cosa può fare:

Forma	Direzione	Cosa può fare
REST API (`/api/v1`)	è il vostro programma a chiedere	solo lettura: risponde esclusivamente a `GET`, nessuna operazione modifica nulla
MCP (`/api/mcp`)	è un’applicazione AI a chiedere	lettura degli stessi dati e inoltre scritture ristrette dietro ambiti sensibili, che una persona concede esplicitamente: `automations:write` (bozza di automazione disattivata e proposta di modifica di una in funzione, che pubblica una persona), `coupons:write` e `coupons:delete` (coupon sconto con anteprima e conferma), `affiliate:write` (gestione del programma partner: account del partner, testi del portale, modelli, campagne, politica dei documenti), `affiliate:approve` (decisione su una singola provvigione indicata, i pagamenti restano nell’applicazione), `availabilities:draft` (proposta di modifica del catalogo delle disponibilità, che nell’e-shop scrive solo una persona approvandola nell’applicazione) e `claims-settings:draft` (proposta di modifica delle impostazioni dei reclami, che scrive solo una persona approvandola nell’applicazione). Inoltre `claims-routes:draft`, `product-content:draft` e `category-content:draft`: proposta di trasporto di ritorno dei reclami e di testi di prodotti e categorie, che scrive una persona approvandola nell’applicazione, oppure subito se il cliente attiva consapevolmente la scrittura autonoma per quell’area. Nient’altro nasce o cambia tramite MCP
Webhook in uscita	è MitoOps a inviare a voi	un messaggio firmato su un evento (ordine, pagamento, spedizione, magazzino, fattura, reclamo) al vostro indirizzo

L’interfaccia espone attualmente 130 strumenti MCP (102 in lettura, 28 in scrittura dietro ambiti sensibili: bozza e revisione di un’automazione, coupon di sconto, gestione del programma di affiliazione e proposte di modifica delle disponibilità, delle impostazioni e della spedizione di reso dei reclami e dei testi di prodotti e categorie, che registra solo una persona approvandole nell’app, salvo che il cliente attivi consapevolmente la scrittura autonoma per quell’area), 101 percorsi REST (tutti in sola lettura) e 32 ambiti di autorizzazione, di cui 13 sensibili, in 19 aree di dati. I numeri derivano dal catalogo dell’app durante la generazione di questa pagina, nessuno li scrive a mano.

Cosa leggete tramite REST e MCP: e-shop, ordini, prodotti e categorie, scorte con la cronologia dei movimenti, fatture e note di credito, spedizioni e statistiche di consegna, traffico e canali, report finanziari e vendite, rubrica clienti e analisi dei clienti in pseudonimi, fornitori, reclami con statistiche, programma partner, automazioni, catalogo delle disponibilità degli e-shop, endpoint webhook e piano dell’account con i limiti.

Tramite MCP non si può modificare un ordine o il suo stato, la giacenza, un prodotto o la disponibilità assegnata a un prodotto, un prezzo, emettere un documento, effettuare un rimborso, gestire gli endpoint webhook, attivare un’automazione, approvare provvigioni in blocco né pagare un partner. Ogni scrittura sta dietro un proprio ambito sensibile: bozza di automazione disattivata (la attiva solo una persona nell’applicazione), coupon sconto (anteprima e conferma), gestione del programma partner, decisione su una singola provvigione indicata e proposta di modifica del catalogo delle disponibilità (nell’e-shop la scrive solo una persona, quando la approva nell’applicazione). REST non ha affatto chiamate di scrittura. I dati di accesso ai corrieri, all’e-shop e ad analytics non si leggono tramite nulla.

REST: solo lettura

L’indirizzo è /api/v1 sul dominio della vostra applicazione. Chiamate, parametri, forma della risposta, periodo e paginazione sono nell’interfaccia REST. Una descrizione leggibile dalle macchine si trova su /api/v1/openapi.json dietro la stessa chiave; una persona che ha effettuato l’accesso la apre anche dalla schermata Impostazioni → API & MCP. La descrizione nasce dalla stessa fonte dell’interfaccia, quindi non se ne discosta.

Qualsiasi cosa diversa da GET riceve 405 prima che il server guardi la chiave. Non è una limitazione temporanea: REST v1 non ha chiamate di scrittura e le scritture MCP di proposito non vi sono entrate. Una proposta di modifica delle disponibilità tramite REST la potete solo leggere (il suo stato), non prepararla.

MCP: lettura e scritture ristrette

L’indirizzo è /api/mcp. MitoOps è un server MCP remoto standard (Model Context Protocol, un protocollo aperto indipendente dal fornitore di AI); si collega qualsiasi applicazione che supporti MCP remoto tramite HTTP con OAuth o con chiave di accesso. Claude.ai è un client verificato in produzione; la procedura esatta è nell’interfaccia MCP.

Gli strumenti MCP poggiano sulle stesse funzionalità di REST: non è una seconda interfaccia con query proprie. L’elenco degli strumenti segue gli ambiti della chiave o del consenso: uno strumento fuori ambito per l’applicazione non esiste. Ogni strumento porta le annotazioni secondo la revisione del protocollo 2026-07-28 (readOnlyHint, destructiveHint, idempotentHint), da cui l’applicazione AI capisce se si tratta di lettura o di scrittura.

OAuth: collegamento per conto di una persona

Un’applicazione AI che supporta MCP remoto con OAuth non si collega con una chiave. Le indicate l’indirizzo /api/mcp, lei vi manda all’accesso a MitoOps (anche con il secondo fattore) e nella schermata del consenso scegliete cosa può leggere, quali e-shop riguarda e quali scritture può fare (bozze di automazioni, coupon, gestione del programma partner, decisione sulle provvigioni, proposte di modifica delle disponibilità). L’applicazione non vede mai la password.

Cosa viene concesso lo decide la persona che ha effettuato l’accesso, e mai più di quanto possa lei stessa. Chi non ha il diritto ai prezzi di acquisto non ha modo di concederlo ad altri; chi non può modificare le automazioni non vedrà affatto l’ambito automations:write nella schermata del consenso. Il consenso OAuth non consuma una chiave di accesso dal limite del piano, ma richiede un piano con API & MCP: senza di esso la schermata del consenso non si apre e dice perché.

L’autorizzazione si può revocare in qualsiasi momento in Impostazioni → API & MCP e tutti gli accessi che ne derivano smettono di valere nello stesso istante.

Chiave di accesso

Per un server che chiama un server o per un vostro programma:

Nell’applicazione aprite Impostazioni → API & MCP e premete Nuova chiave.
Inserite un nome con cui riconoscerete la chiave in seguito.
Scegliete ambiti, e-shop e interfacce (REST, MCP o entrambe).
Scegliete la validità e create la chiave.

La chiave si invia nell’intestazione; nell’indirizzo di proposito non viene accettata (gli indirizzi finiscono nei log e nella cronologia del browser):

Authorization: Bearer <la vostra chiave>

Ambiti di autorizzazione

Né la chiave né il consenso vedono mai più di quanto è stato loro assegnato. La tabella nasce dal catalogo dell’applicazione:

Ambito	Accesso	Sensibile	A cosa dà accesso
`stores:read`	lettura	no	elenco degli e-shop con codice
`orders:read`	lettura	no	ordini, righe comprese; dell’indirizzo solo paese e città, importi solo con `reports:read`
`products:read`	lettura	no	prodotti, categorie e prezzo di vendita dalla scheda prodotto
`invoices:read`	lettura	no	fatture con righe, note di credito e fatture di acconto
`shipping:read`	lettura	no	spedizioni, eventi di tracciamento, corrieri (senza dati di accesso) e statistiche di consegna
`analytics:read`	lettura	no	traffico, canali, risultati nella ricerca e copertura degli ordini da parte della misurazione
`search-console:read`	lettura	no	prestazioni nella Ricerca Google dall’archivio sincronizzato: giorni, query, pagine, paesi e dispositivi
`inventory:read`	lettura	no	giacenze e cronologia dei movimenti di magazzino
`reports:read`	lettura	sensibile	fatturato a confronto e per mese, pubblicità (spesa, budget, ROAS, incidenza pubblicitaria, CPA, MER), quando arrivano gli ordini, fonti del fatturato; riepilogo finanziario del periodo (fatturato, IVA, costi, risultato), vendite per prodotto, rendimento per ordine, clienti come pseudonimi e importi nell’elenco massivo degli ordini
`purchasing:read`	lettura	sensibile	fornitori, le loro offerte e le componenti di costo
`claims:read`	lettura	no	reclami e resi con i collegamenti a ordine, nota di credito e spedizione di reso, cronologia ed e-mail inviate del caso; statistiche e processi del modulo
`automations:read`	lettura	no	catalogo di trigger e azioni, elenco delle automazioni, loro impostazione, cronologia delle esecuzioni e validazione della bozza
`automations:write`	scrittura	sensibile	creazione o modifica di una bozza disattivata di automazione e proposta di modifica di un’automazione attiva (revisione); attivare la bozza e pubblicare la revisione può solo una persona nell’applicazione, l’automazione in funzione non cambia per effetto della proposta
`webhooks:read`	lettura	no	catalogo degli eventi, endpoint senza segreto e registro delle consegne senza corpo
`account:read`	lettura	no	piano, funzioni attive e limiti con l’utilizzo attuale
`affiliate:read`	lettura	no	programma partner: panoramica, partner, campagne, codici sconto, conversioni, pagamenti, statistiche, impostazioni, documenti, portale pubblico, modelli di e-mail, articoli di aiuto e richieste di codice; contatto del partner solo con `personal-data:read`, dati bancari e fiscali mai
`affiliate:write`	scrittura	sensibile	gestione del programma partner: decisione sull’account del partner (approvare, rifiutare, sospendere), gestione della richiesta di codice, impostazioni del programma escluso il denaro, testi del portale, articoli di aiuto, modelli di e-mail, campagne e politica dei documenti; la decisione sulla provvigione ha un ambito proprio, i pagamenti restano nell’applicazione
`affiliate:approve`	scrittura	sensibile	decisione su una singola provvigione del programma partner in base all’id della conversione: approvare, rifiutare o annullare (rifiuto e annullamento con motivo, il partner riceve un’e-mail); una provvigione pagata non viene stornata, l’approvazione in blocco e i pagamenti dall’esterno non esistono
`customers:read`	lettura	no	rubrica clienti: pseudonimo, e-shop, paese, lingua, conteggi e date dell’intero ciclo di vita; nome, azienda, e-mail e telefono solo con `personal-data:read`, fatturato e LTV solo con `reports:read`
`coupons:read`	lettura	no	coupon sconto dell’e-shop con valore dello sconto e validità, supporto della piattaforma, link di attivazione e sua predisposizione
`coupons:write`	scrittura	sensibile	creazione di un coupon sugli e-shop selezionati (uno esistente con parametri diversi non viene sovrascritto senza consenso esplicito)
`coupons:delete`	scrittura	sensibile	eliminazione irreversibile di un coupon sull’e-shop selezionato dopo anteprima e conferma esplicita; un coupon con una dipendenza attiva (AI Mailing, finestra di registrazione, campagna programmata, partner) non viene eliminato
`chatbot:read`	lettura	no	statistiche del chatbot web per il periodo: visualizzazioni e clic del messaggio (tasso di clic), aperture della chat con la loro origine, numero di conversazioni e messaggi, esiti, valutazioni dei clienti, imbuto dell’iscrizione alla newsletter e valutazione deterministica degli argomenti delle conversazioni (quote, prodotti, candidati a lacune): solo totali
`chatbot-conversations:read`	lettura	sensibile	conversazioni dei clienti con il chatbot web: elenco con la prima domanda e trascrizione con le fonti delle risposte del bot; il cliente è solo una chiave casuale della conversazione, e-mail, telefono e IBAN nel testo solo con `personal-data:read`, altrimenti sostituiti da un segnaposto; solo entro la conservazione dell’e-shop
`availabilities:draft`	scrittura	sensibile	proposta di modifica del catalogo delle disponibilità dell’e-shop (creare, modificare, eliminare) con anteprima; nell’e-shop la scrive solo una persona autorizzata quando la approva nell’applicazione, altrimenti scade dopo 24 ore; non modifica l’assegnazione delle disponibilità ai prodotti né le giacenze
`claims-settings:read`	lettura	no	modelli di e-mail e di verbali dei reclami, impostazioni del modulo, etichette, trasporto di reso e modulo sull’e-shop; senza token di accesso
`claims-settings:draft`	scrittura	sensibile	proposta di modifica di processi, stati, etichette e testi dei modelli dei reclami con anteprima; la scrive solo una persona autorizzata approvandola nell’applicazione, altrimenti scade dopo 72 ore; non elimina nulla
`claims-routes:draft`	scrittura	sensibile	una proposta di creare, modificare, attivare o disattivare un percorso di reso, verificata come sullo schermo; la scrive una persona approvandola nell’app, oppure subito se il cliente ha attivato consapevolmente la scrittura autonoma per quell’area; non elimina mai un percorso
`product-content:read`	lettura	no	descrizione, descrizione breve e testi SEO di un prodotto direttamente dall’e-shop, con impronta e scrivibilità di ogni campo
`product-content:draft`	scrittura	sensibile	proposta di nuovi testi dei prodotti (al massimo 30 alla volta), solo campi di contenuto, mai prezzo, giacenza, codice o EAN; la scrive una persona approvandola, oppure subito con la scrittura autonoma attivata consapevolmente
`category-content:read`	lettura	no	descrizione superiore e inferiore e testi SEO di una categoria, con impronta e scrivibilità secondo la piattaforma dell’e-shop
`category-content:draft`	scrittura	sensibile	proposta di nuovi testi delle categorie (al massimo 30 alla volta), solo i campi che la piattaforma dell’e-shop sa scrivere; la scrive una persona approvandola, oppure subito con la scrittura autonoma attivata consapevolmente

Gli ambiti sensibili non sono preselezionati né nella schermata di emissione della chiave né in quella del consenso: una persona deve spuntarli consapevolmente. purchase-prices:read e personal-data:read non hanno uno strumento proprio; decidono dei campi nelle risposte degli altri. Un campo mancante non è zero: manca.

Gli ambiti sono un impegno pubblico: cambiano solo in modo retrocompatibile e una credenziale emessa in precedenza non eredita un nuovo ambito (gli ambiti vi sono scritti per nome). Per questo una chiave o un consenso più vecchi non hanno ricevuto i dati personali quando il 2/9/2026 è nato per essi un ambito proprio, e non riceveranno nemmeno la scrittura delle bozze: per quella serve un nuovo consenso o una nuova chiave.

A una chiave esistente si può aggiungere un nuovo ambito anche senza sostituire la chiave: Impostazioni → API & MCP → Modifica ambiti. Il valore della chiave resta lo stesso, l’integrazione che la usa continua a funzionare e riceve il nuovo ambito dalla richiesta successiva. La modifica la fa una persona autorizzata a gestire le chiavi; piano e ambiti sensibili sono verificati come al rilascio.

Dati personali

L’interfaccia fornisce dati operativi, quelli personali solo con l’ambito personal-data:read:

Ordini e reclami senza di esso restituiscono solo paese e città, non nome, e-mail, telefono né via.
La rubrica clienti (customers:read) da sola fornisce solo pseudonimo, e-shop, paese, lingua, conteggi e date. Nome, azienda, e-mail, telefono e genere di marketing li aggiunge solo personal-data:read, fatturato e LTV solo reports:read: un campo mancante viene rimosso, non azzerato.
L’analisi dei clienti (customers/performance) non ha affatto dati personali: il cliente è uno pseudonimo (impronta dell’e-mail), lo stesso di customerEmailHash sui documenti e nella rubrica.
Il contatto del fornitore e del partner del programma richiede lo stesso ambito.
Le conversazioni con il chatbot web (chatbot-conversations:read, sensibile) portano solo una chiave casuale della conversazione, senza nome, e-mail, IP o cookie. E-mail, telefono e IBAN che il cliente ha scritto nel testo li fornisce solo personal-data:read; senza di esso al loro posto c’è un segnaposto.
I dati bancari e fiscali dei partner (IBAN, partita IVA, codice fiscale, dati di fatturazione dei pagamenti), le note interne, le password e i segreti del secondo fattore non vengono forniti mai: nessun ambito li apre.
I webhook inviano identificatori e stati, non il contenuto dell’ordine né i dati del cliente.

Ogni chiamata viene registrata nell’audit senza i valori di input, solo con i nomi dei campi e un’impronta.

Automazioni: la scrittura sicura della bozza

Un assistente AI può proporre un’automazione, non può attivarla. Con l’ambito automations:write (sensibile, mai preselezionato, viene offerto solo a una persona con il diritto di modificare le automazioni):

automations_create_draft crea una bozza nello stato disattivato: non tocca la versione pubblicata, i trigger né l’esecuzione;
automations_update_draft modifica solo una bozza che nessuno ha ancora pubblicato; una bozza in lavorazione nell’editor dell’applicazione non viene sovrascritta;
la bozza compare in Automazioni come ogni bozza in lavorazione e attivarla, pubblicarla o avviarla può solo una persona nell’applicazione con il diritto di approvazione;
automations_revision_create_draft propone una modifica di un’automazione pubblicata e anche attiva come revisione; la versione in funzione non cambia finché una persona non carica la revisione nell’editor e la pubblica (automations_revision_update_draft, automations_revision_discard_draft).

I valori dei campi che nell’editor si scelgono da un elenco (stato dell’ordine, spedizione, pagamento, stato del reclamo…) li restituisce automations_options nella forma che l’editor salva. Un valore che nell’e-shop non esiste e un testo segnaposto del tipo DOPLNIT_… sono un errore di validazione, non un successo.

La creazione è idempotente tramite clientRequestId, la modifica richiede expectedVersion ed entrambe richiedono catalogVersion da automations_catalog: un catalogo obsoleto è un conflitto, non una scrittura silenziosa. Una bozza che fa riferimento a un trigger sconosciuto, a un e-shop fuori ambito o a un endpoint webhook altrui non viene salvata. Dettagli nell’interfaccia MCP.

Disponibilità: una proposta di modifica approvata da una persona

Le disponibilità sono le voci del catalogo di un e-shop specifico che l’e-shop mostra accanto al prodotto, ad esempio Disponibile, Su ordinazione o Preordine: nome, descrizione, rifornimento e consegna in ore, significato per Google Shopping e colore. Non sono la giacenza.

availabilities_list e GET /availabilities?market= (ambito products:read) restituiscono il catalogo di un e-shop; market è obbligatorio. Il campo manageable dice se il catalogo di quell’e-shop si può modificare in MitoOps, e reason perché no: PLATFORMA (la piattaforma non lo consente), BEZ_ROZSIRENIA (all’e-shop WooCommerce manca il plugin MitoOps) o PROSTREDIE (la scrittura negli e-shop è disattivata nell’ambiente).
availabilities_change_draft (solo MCP, ambito sensibile availabilities:draft) non scrive nulla nell’e-shop. Verifica la modifica, la salva come proposta valida 24 ore e restituisce l’anteprima (campo prima e dopo, avvisi, blocchi), draftId e approvalUrl.
Nell’e-shop la proposta la scrive solo una persona nell’applicazione con il pulsante Approva e scrivi in Magazzino → Disponibilità → Gestione, oppure la rifiuta. Decidono i suoi diritti al momento del clic, non l’ambito della chiave o del consenso. Né il modello né la chiave di accesso scrivono nulla nell’e-shop senza una persona.
availabilities_draft_get e GET /availabilities/drafts/:draftId (ambito products:read) restituiscono lo stato della proposta: pending, writing, executed, partial, failed, rejected o expired.

L’ambito availabilities:draft viene offerto solo a una persona che potrebbe anche approvare la modifica (diritto di gestire la sincronizzazione del magazzino e di modificare i prodotti). Una chiave o un consenso esistenti non lo ereditano. REST v1 resta in sola lettura. I parametri della proposta sono nell’interfaccia MCP, la schermata di approvazione nella guida Disponibilità.

Reclami: impostazioni in lettura e proposta di modifica

claims_settings (ambito claims:read) restituisce i processi con ID e nomi di tipi, passaggi e stati e le etichette; con l’ambito claims-settings:read anche le impostazioni del modulo.
claims_templates e claims_configuration (ambito claims-settings:read) restituiscono i modelli di e-mail e di verbali (oggetto, testo, quando e se vengono inviati automaticamente) e le altre impostazioni: etichette, campi, trasporto di reso e modulo sull’e-shop, senza il token di integrazione.
claims_get riporta anche la cronologia del caso, le e-mail inviate e le etichette; il testo dei messaggi solo con personal-data:read.
claims_config_change_draft (solo MCP, ambito sensibile claims-settings:draft) non modifica le impostazioni. Salva una proposta di modifica di processi, stati, etichette e testi dei modelli per 72 ore con anteprima e approvalUrl; la scrive solo una persona con il diritto di gestire le impostazioni con il pulsante Approva e scrivi in Reclami → Impostazioni, per intero o per niente. Lo stato lo restituisce claims_config_draft_get.

I parametri sono nell’interfaccia MCP.

Spedizione di reso, testi dei prodotti e scrittura autonoma

claims_routes (ambito claims-settings:read o uno qualsiasi degli ambiti di proposta dei reclami) restituisce i percorsi di spedizione di reso, gli indirizzi del destinatario, i profili dei corrieri con ID, indicatore di reso e copertura, e le chiavi dei tipi di caso. claims_routes_change_draft (solo MCP, ambito sensibile claims-routes:draft) propone di creare, modificare, attivare o disattivare un percorso. Il server lo verifica esattamente come lo schermo: profilo con reso attivato, copertura del corriere, indirizzo e tipi esistenti, prezzo non negativo e nessun conflitto con un percorso attivo. L’eliminazione di un percorso tramite MCP non esiste.
products_content_get e GET /products/:code/content?market= (ambito product-content:read) restituiscono descrizione, descrizione breve e testi SEO di un prodotto direttamente dall’e-shop, ogni campo con impronta (hash) e l’indicazione se la piattaforma può scriverlo. categories_content_get e GET /categories/:guid/content?market= (ambito category-content:read) restituiscono lo stesso per una categoria.
products_content_change_draft e categories_content_change_draft (solo MCP, ambiti sensibili product-content:draft e category-content:draft) propongono nuovi testi, al massimo 30 elementi alla volta. Accettano solo campi di contenuto; prezzo, giacenza, disponibilità, codice, EAN o nome non si possono cambiare così. L’HTML viene verificato: nessuno script tranne un blocco JSON-LD FAQPage, nessun on…, javascript: o iframe. All’approvazione il testo viene confrontato con lo stato dell’e-shop e, se qualcuno lo ha modificato nel frattempo, non viene scritto nulla (CHANGED_SINCE_DRAFT). Se l’e-shop modifica il testo al salvataggio, il risultato lo dice (MODIFIED_BY_PLATFORM). Le proposte si approvano in Magazzino → Modifiche prodotti. Su WooCommerce una proposta con script (anche JSON-LD) o con barra rovesciata viene bloccata (PLATFORM_STRIPS_SCRIPT, PLATFORM_STRIPS_BACKSLASH): WordPress li rimuove al salvataggio e i clienti vedrebbero il resto come testo.
products_content_policy e GET /product-content/policy?market= (ambito product-content:read) dicono, senza chiamare l’e-shop, cosa può fare la sua chiave con i testi in un dato e-shop: se può leggere (readEnabled) e proporre (draftEnabled, proposte solo tramite MCP), quali campi scrive la piattaforma (supportedFields; i campi SEO su WooCommerce solo con un plugin SEO), la modalità di approvazione (approvalMode: human, autonomous o disabled) e se una proposta viene scritta automaticamente (autonomousWriteEnabled), i limiti delle proposte e l’algoritmo delle impronte (sha256). Un e-shop sospeso, una piattaforma non supportata o una chiave dell’e-shop di sola lettura sono status e reason nella risposta, non un errore. Il campo category riporta lo stesso per le categorie. Il campo structuredData indica se la piattaforma conserva i dati strutturati nella descrizione del prodotto: su WooCommerce no (NOT_SUPPORTED, PLATFORM_STRIPS_SCRIPT; lì i dati strutturati sono gestiti dal tema del negozio, THEME_MANAGED), su Shoptet sì (un blocco FAQPage).
Scrittura autonoma. Per impostazione predefinita ogni proposta (impostazioni e percorsi dei reclami, testi di prodotti e categorie) viene scritta solo dopo l’approvazione di una persona. Un amministratore può attivarla per singola area in Impostazioni → API & MCP → Scrittura tramite AI. La proposta viene allora scritta subito, nello stesso modo di un’approvazione, a nome della persona che ha concesso l’accesso all’AI, e solo se quella persona ha in questo momento il diritto di approvare la modifica. Altrimenti la proposta attende e la risposta spiega perché. Ogni cambio di modalità viene registrato.

Chiavi e consensi esistenti non ereditano i nuovi ambiti; serve un nuovo consenso.

Webhook in uscita

REST e MCP sono letture su richiesta. Quando il vostro sistema deve sapere di un evento subito (nuovo ordine, pagamento, cambio di stato, spedizione, consegna, movimento di scorte, fattura, reclamo) lo riceve tramite i webhook in uscita: MitoOps invia al vostro indirizzo una breve busta con gli identificatori, firmata HMAC-SHA256, con ripetizione in caso di fallimento e un registro dei tentativi. Il dettaglio il sistema lo carica poi tramite REST.

Le iscrizioni le crea una persona nell’applicazione nella stessa schermata delle chiavi; tramite REST e MCP gli endpoint si possono solo leggere (webhooks:read, senza segreto). Un endpoint si può usare anche come passaggio di un’automazione. Dettagli nei webhook in uscita.

Limiti dell’account

API & MCP e webhook fanno parte di ogni piano a pagamento da Start in su. I piani si differenziano per il numero di chiavi attive e di endpoint, non per ciò che si può leggere:

Piano	API & MCP	Chiavi di accesso attive	Endpoint webhook
Versione di prova	—	0	0
Principiante	—	0	0
Start	sì	1	5
Crescita	sì	2	20
Pro	sì	5	50
Su misura	sì	secondo accordo	secondo accordo

I limiti li applica il server: un tentativo di creare un’altra chiave o un altro endpoint oltre il limite termina con un rifiuto motivato. La sostituzione di una chiave e la rotazione del segreto di un endpoint non consumano posto. Il passaggio a un piano inferiore non annulla le chiavi né gli endpoint esistenti: non se ne possono creare di nuovi finché il numero non scende sotto il nuovo tetto. Il collegamento tramite OAuth non consuma chiavi.

I valori attuali per il vostro account, utilizzo compreso (automazioni attive, esecuzioni nel mese, e-mail, crediti), li fornisce account_entitlements / GET /account/entitlements con l’ambito account:read. Riporta solo piano, funzioni e limiti, senza dati di fatturazione. Il listino attuale è su mitoops.com/cennik.

Limiti di chiamata

Limite	Su cosa si misura	Quanto
prima della verifica	sull’indirizzo da cui chiamate	300 chiamate / 60 s
dopo la verifica	sulla chiave specifica	600 chiamate / 60 s

Il primo impedisce di indovinare le chiavi, il secondo è vostro e non lo condividete con nessuno. Il superamento è 429 con le intestazioni RateLimit-*. Non è una grandezza del piano: il numero di chiamate non viene addebitato.

Errori

In caso di errore la risposta ha sempre la stessa forma e porta un codice:

{ "error": { "code": "store_required", "message": "…", "requestId": "…" } }

Stato	Codice	Quando
`400`	`invalid_request`	il parametro non corrisponde alla descrizione (data errata, periodo invertito, cursore non valido)
`400`	`store_required`	chiamata sui dati di un e-shop senza `market`
`401`	`unauthorized`	chiave mancante, sconosciuta, annullata o non valida
`403`	`forbidden`	la chiave non ha l’ambito necessario
`403`	`store_forbidden`	e-shop fuori dall’ambito della chiave
`404`	`not_found`	il record non esiste (anche quando appartiene a un altro e-shop)
`405`	—	qualsiasi cosa diversa da `GET` (REST)
`409`	`conflict`	la scrittura della bozza ha trovato un’altra versione, un `clientRequestId` già usato o un catalogo cambiato (MCP)
`429`	`rate_limited`	superato il limite tecnico di chiamate

Il motivo del rifiuto con 401 non viene distinto: la differenza aiuterebbe chi tenta di indovinare le chiavi. Indicate il requestId quando segnalate un problema all’assistenza. Tramite MCP un errore che l’assistente sa correggere arriva come risultato dello strumento con l’indicatore isError; un errore di protocollo come errore JSON-RPC.

Esempi

# Ordini per un periodo, per pagine
curl -H "Authorization: Bearer <la vostra chiave>" \
  "https://<il vostro indirizzo>/api/v1/orders?market=sk&from=2026-08-01&to=2026-08-31&limit=50"

# Statistiche di consegna di agosto
curl -H "Authorization: Bearer <la vostra chiave>" \
  "https://<il vostro indirizzo>/api/v1/shipping/stats?market=sk&from=2026-08-01&to=2026-08-31"

# Statistiche dei reclami di agosto
curl -H "Authorization: Bearer <la vostra chiave>" \
  "https://<il vostro indirizzo>/api/v1/claims/statistics?market=sk&from=2026-08-01&to=2026-08-31"

# Piano e limiti dell'account con l'utilizzo
curl -H "Authorization: Bearer <la vostra chiave>" \
  "https://<il vostro indirizzo>/api/v1/account/entitlements"

Domande a cui, dopo il collegamento, Claude.ai risponde con i dati di MitoOps: “Qual è stata la mediana del tempo di consegna di DHL e GLS ad agosto?”, “Quanti ordini sono arrivati da ChatGPT?”, “Qual è il margine del prodotto X nell’ultimo mese?” (con purchase-prices:read), “Quanti reclami sono oltre il termine?”, “Proponi un’automazione che, per un ordine non pagato, dopo tre giorni invii un promemoria” (con automations:write nasce una bozza disattivata), “Sull’e-shop SK rinomina la disponibilità Su ordinazione in Entro 5 giorni” (con availabilities:draft nasce una proposta che scrivete approvandola nell’applicazione).

Sicurezza

Isolamento degli spazi dei clienti. Il cliente proviene esclusivamente dalla credenziale; ogni cliente ha un proprio database.
L’ambito degli e-shop è l’intersezione tra l’elenco della credenziale e gli e-shop che avete collegati in quel momento. Nelle chiamate sui dati di un singolo e-shop market è obbligatorio: un e-shop mancante è 400, un e-shop fuori ambito 403.
Diritti della persona. La schermata del consenso offre solo gli ambiti che la persona che ha effettuato l’accesso ha lei stessa; decide l’insieme di autorizzazioni proprio dell’account.
I limiti delle scritture li impone il servizio, non un’annotazione: la bozza di automazione nasce sempre disattivata, un’automazione pubblicata non cambia tramite MCP e una proposta di modifica delle disponibilità non scrive nulla nell’e-shop finché una persona non la approva nell’applicazione.
Validità e revoca. Il token di accesso OAuth vale un’ora, quello di rinnovo 30 giorni; un consenso revocato blocca ogni token che ne è derivato. Le chiavi si possono annullare o sostituire immediatamente.
Audit. Ogni chiamata è registrata con il nome della funzionalità, l’interfaccia e l’impronta dell’input, senza valori.
Su cosa non si può contare: indirizzi non pubblici dell’applicazione (l’interfaccia è /api/v1 e /api/mcp, nient’altro), accesso diretto al database (non esiste) e dati di accesso (l’interfaccia non li fornisce).