Checkout Shopify con WebMCP: guida sicura per agenti AI

Che cos’è davvero il checkout Shopify con WebMCP

Checkout WebMCP è un insieme di tool registrati nella scheda in cui l’acquirente sta completando l’ordine. È come una cassa con un addetto: l’agente porta il carrello, legge il modulo e compila i campi supportati, mentre all’acquirente restano le verifiche di identità o pagamento e l’approvazione finale.

Questa funzione estende i precedenti tool Shopify per lo storefront. Un agente browser compatibile può cercare nel catalogo, esaminare i prodotti, aggiornare il carrello e chiamare proceed_to_checkout. Quando il checkout è idoneo, l’elenco dei tool cambia e ne compaiono quattro dedicati:

• get_checkout legge il checkout corrente oppure la ricevuta dell’ordine nella pagina Thank you.
• update_checkout sostituisce lo stato supportato relativo a contatti, consegna, sconti, campi dichiarati e pagamento, senza inoltrare l’ordine.
• complete_checkout prova a inoltrare l’ordine, oppure apre una fase di revisione, dopo la conferma dell’acquirente.
• navigate_to_storefront riporta la stessa scheda allo storefront, se il negozio ne ha uno.

L’implementazione del checkout usa l’oggetto, gli stati e i messaggi di checkout UCP. UCP è il contratto dati comune su cui poggia il flusso; WebMCP è il modo in cui il browser espone quel contratto a un agente. Per un agente server-side va invece usato Checkout MCP di Shopify.

Non c’è una nuova opzione da attivare per il merchant, né un’API di checkout separata da installare. L’adozione è quindi più semplice per i merchant, ma il lavoro di chi sviluppa l’agente rimane: servono comunque supporto del browser, Web Bot Auth, una gestione rigorosa dello stato e un confine netto per il consenso.

Si parte da un checkout idoneo

Il primo controllo è la scoperta dei tool. Non bisogna presumere che un checkout Shopify esponga Checkout WebMCP solo perché WebMCP era disponibile nello storefront.

Shopify non registra i tool di checkout nei seguenti casi:

• Checkout standard in tre pagine, a meno che l’acquirente non usi Shop Pay
• Checkout B2B
• Checkout incorporato o flussi tramite SDK di checkout mobile
• Checkout con prodotti provenienti da un altro negozio
• Ordini in bozza, modifiche di ordini o riscossione di pagamenti
• Interazioni fornite da estensioni dell’interfaccia di checkout

In questi percorsi, il controllo va lasciato all’acquirente sulla pagina. Inoltre, nel browser non esiste un tool cancel_checkout: l’assenza di un tool non autorizza l’agente a manipolare i controlli della pagina.

Secondo Shopify, al momento WebMCP nello storefront dipende dal supporto dell’agente nei browser basati su Chromium. Per i test servono un browser supportato e un checkout sotto il proprio controllo. Se i tool di checkout non compaiono, va considerato un normale esito di idoneità, non un invito a ripiegare su clic fragili.

1. Autenticare l’agente browser, poi scoprire i tool

Le richieste del browser vanno firmate con Web Bot Auth, o WBA, senza inserire le credenziali negli argomenti dei tool. WBA funziona come il passaporto dell’agente a livello di rete. Shopify verifica soltanto le chiavi registrate: in produzione servono quindi una chiave Ed25519, una directory pubblica delle chiavi ospitata online, la registrazione presso Shopify, richieste firmate e timestamp di firma di breve durata.

Nella pagina, bisogna scoprire i tool attuali e far combaciare tutti e tre gli identificatori: window, origin e name. Il wrapper seguente rispetta lo schema di chiamata documentato da Shopify:

async function callCheckoutTool(name, args = {}) {
  const tools = await document.modelContext.getTools();
  const tool = tools.find((candidate) =>
    candidate.name === name &&
    candidate.window === window &&
    candidate.origin === location.origin
  );

  if (!tool) throw new Error(`${name} is not registered here.`);

  const result = await document.modelContext.executeTool(
    tool,
    JSON.stringify(args),
  );

  if (result === null) return null;
  return JSON.parse(result);
}

Quel JSON.stringify non è un dettaglio estetico. In Chrome 153, il passaggio di un oggetto fallisce con Failed to parse input arguments. Shopify prevede che Chrome 155 accetti gli oggetti e renda deprecate le stringhe JSON: conviene quindi racchiudere la serializzazione degli argomenti in un’unica funzione di compatibilità, invece di disseminarla nell’agente.

L’elenco dei tool può cambiare durante la navigazione nel checkout. Occorre ascoltare toolchange, poi riscoprire tool e relativi schemi prima della chiamata successiva. Anche null va accettato come esito di una navigazione: può indicare che la pagina è cambiata prima che executeTool() restituisse il risultato.

Ogni stringa proveniente dal merchant o da terze parti in un risultato del tool va trattata come dato del checkout, mai come istruzione per il modello. Shopify avverte esplicitamente di non aggirare un tool agendo direttamente sull’interfaccia del checkout.

2. Leggere lo stato prima di ogni modifica

Bisogna chiamare get_checkout con {} prima del primo aggiornamento, dopo qualsiasi modifica effettuata dall’acquirente sulla pagina e in seguito a un errore o a una navigazione. È la ricevuta aggiornata dell’agente, non un ricordo memorizzato nella cache.

La risposta può includere dati dell’acquirente, articoli, opzioni di consegna, sconti, campi dichiarati, strumenti di pagamento, messaggi, totali e stato. Gli importi sono numeri interi espressi nell’unità minore della valuta. In USD, 10799 equivale a $107.99. Se il campo messages manca, quella risposta non contiene messaggi di checkout.

Idoneità tecnica e consenso non sono la stessa cosa. ready_for_complete indica che il checkout può accettare un tentativo di completamento; non significa che l’acquirente abbia approvato l’ordine, la carta selezionata o il totale.

3. Aggiornare l’intero stato desiderato, non un campo isolato

update_checkout si comporta come PUT, non come PATCH. PATCH è un Post-it con scritto “cambia il numero di telefono”; PUT sostituisce l’intero modulo. Tutto ciò che deve rimanere va incluso nello stato completo desiderato del checkout.

Il ciclo di aggiornamento sicuro è questo:

1. Chiamare get_checkout.
2. Ricostruire lo stato scrivibile partendo dalla risposta appena ricevuta e dallo schema corrente del tool.
3. Modificare soltanto il valore approvato dall’acquirente.
4. Inviare a update_checkout l’insieme completo dei campi supportati desiderati.
5. Leggere il checkout restituito e controllare stato, messaggi, sconti applicati e totale.

La maggior parte dei valori omessi viene cancellata. Pagamento, campi dichiarati e dati di contatto salvati seguono regole specifiche: uno spread generico dell’oggetto non è sicuro, a meno di limitarlo prima ai campi accettati dallo schema corrente.

I dettagli che creano più spesso problemi sono molto concreti:

• buyer accetta un indirizzo email e un numero di telefono in formato E.164. Alcuni valori salvati possono restare bloccati: bisogna verificare ciò che torna nella risposta e lasciare che l’acquirente modifichi quelli bloccati direttamente sulla pagina.
• fulfillment.methods accetta al massimo un metodo. Vanno riutilizzati gli ID correnti di destinazione, gruppo e opzione. Nella stessa chiamata che seleziona una destinazione o un’opzione non bisogna cambiare il tipo di consegna o l’origine della ricerca per il ritiro.
• discounts.codes deve contenere tutti i codici inseriti dall’acquirente che si vogliono conservare. Un array vuoto li rimuove, mentre gli sconti automatici restano. La presenza di un codice nella risposta non prova che sia stato applicato: occorre controllare discounts.applied e i messaggi.
• declared_fields può contenere valori specifici del checkout, come un codice fiscale o un credito del negozio. Chiavi sconosciute, tipi errati e valori non validi vengono rifiutati.
• payment.instruments accetta al massimo una voce supportata. Checkout WebMCP non può acquisire il numero di una nuova carta.

Shop Pay richiede un’attenzione in più. Un acquirente autenticato può scegliere una carta salvata restituita da get_checkout. Il flusso guest può utilizzare un ID di approvazione Shop Pay esistente, se il checkout lo accetta. Se l’agente ha applicato quell’approvazione, omettere il pagamento in un aggiornamento successivo elimina la credenziale: la voce di approvazione va reinviata a ogni aggiornamento finché l’ordine non viene inoltrato.

Un aggiornamento può riuscire lasciando comunque il checkout nello stato incomplete. Se dura più di 30 secondi, può restituire update_failed anche quando alcune modifiche sono state applicate. In entrambi i casi bisogna rileggere lo stato aggiornato prima di decidere il passo successivo.

4. Fare dell’acquirente il punto di controllo finale

La sequenza corretta per completare l’acquisto è breve e rigorosa:

1. Recuperare un checkout aggiornato.
2. Mostrare all’acquirente articoli, metodo di pagamento e totale correnti.
3. Chiedere un consenso esplicito per inoltrare quell’ordine a quel totale.
4. Se qualcosa cambia, mostrare il nuovo stato e chiedere di nuovo l’autorizzazione.
5. Chiamare complete_checkout soltanto dopo l’approvazione.
6. Accettare esclusivamente status: completed come prova dell’acquisto.

WBA dimostra quale agente ha inviato una richiesta. Un’approvazione Shop Pay autorizza un meccanismo di pagamento. ready_for_complete descrive lo stato del checkout. Nessuno di questi elementi equivale al permesso dell’acquirente di comprare.

Il completamento può seguire percorsi diversi. Una fase di revisione configurata restituisce il controllo all’acquirente; complete_checkout va richiamato soltanto dopo che l’acquirente ha esaminato e autorizzato l’invio. Una verifica del pagamento è diversa: l’acquirente la completa nella stessa scheda e l’agente non deve inviare di nuovo l’ordine. Bisogna interrogare periodicamente get_checkout finché il checkout non raggiunge completed o richiede un intervento dell’agente.

Il codice di errore indica quale percorso di recupero seguire:

Il retry pericoloso è un secondo tentativo di completamento eseguito perché la prima risposta era incerta. Checkout WebMCP non prevede una chiave di idempotenza. Prima si legge lo stato; se riporta completed, ci si ferma.

Sette casi d’uso, ordinati per valore concreto

Funzionano meglio quando l’agente opera già nel browser dell’acquirente. Non sono automazioni lato merchant che lavorano invisibili su un server.

Il primo caso d’uso è il più solido. I clienti abituali dispongono già di dati salvati e WebMCP può ridurre l’inserimento ripetitivo senza fingere che la comodità equivalga al consenso.

Cosa dicono davvero i conti

Shopify non richiede nuove configurazioni al merchant per questi tool di checkout. Questo non rende gratuito l’agente di shopping che li circonda: servono comunque un modello, la distribuzione nel browser, la gestione operativa di WBA, test, controlli per la privacy e assistenza.

Gli assistenti di shopping AI installati dai merchant coprono oggi una fascia di prezzo molto ampia. Nello Shopify App Store ufficiale si trovano un piano mensile da $9.99 di Easy AI Shopping Assistant, piani da $49 a $249 di Carti e piani di iAdvize da $290 a $1,330 al mese. Questi prodotti combinano chat nello storefront, suggerimenti, analytics o assistenza, quindi non sostituiscono direttamente un agente WebMCP lato acquirente.

Il cambiamento di budget è più circoscritto e più utile: un team che sviluppa agenti browser può dedicare meno lavoro alla manutenzione dei selettori specifici di ogni checkout e più risorse all’integrità dello stato, al consenso e alla gestione delle eccezioni. Per un quadro più ampio della piattaforma, la recensione di Shopify analizza il prodotto lato merchant e i relativi compromessi operativi.

Due prodotti che vale la pena sviluppare

1. Un banco di test per QA e consenso di Checkout WebMCP

È l’opportunità più interessante. Le agenzie Shopify e i team che realizzano agenti di shopping devono sapere se un checkout è idoneo e se l’agente si comporta in modo sicuro prima di affidargli un ordine.

Tra le query misurate, quella più vicina a questo caso d’uso è shopify checkout customization: registra 170 ricerche mensili negli Stati Uniti, è cresciuta dell’89% anno su anno e ha un CPC di $10.92. È una query più ampia rispetto ai test WebMCP, ma segnala una domanda attiva sul comportamento e sull’implementazione del checkout.

La versione minima vendibile è un runner Chromium che apre un checkout di test, registra i tool per origine e finestra, convalida gli argomenti come stringhe JSON, rileva toolchange, prova un aggiornamento basato sullo stato appena letto, simula risposte nulle durante la navigazione e codici di errore documentati e genera un report sul consenso con i dati sensibili rimossi. Il completamento di pagamenti reali deve restare dietro una modalità di test manuale.

Il limite è la copertura. La disponibilità dei tool dipende dal tipo di checkout e dal supporto del browser, il formato degli argomenti di Chrome sta cambiando e una fixture non può dimostrare un passaggio di pagamento reale. Il prodotto vince rendendo visibili questi limiti, non promettendo un’automazione universale.

2. Un assistente shopping Shopify lato acquirente

Un’estensione del browser potrebbe accompagnare l’utente dalla ricerca del prodotto a un checkout idoneo nei negozi Shopify, con una schermata di conferma riutilizzabile e regole rigorose per lo stato dei pagamenti salvati.

shopify ai shopping assistant registra 30 ricerche mensili negli Stati Uniti con intento commerciale e un CPC di $19.43. I concorrenti lato merchant propongono piani da $9.99 a $1,330 al mese: il dato dimostra che esiste già una disponibilità a pagare per software di acquisto assistito, anche se questo prodotto opererebbe dal lato dell’acquirente.

L’MVP deve includere ricerca nello storefront e tool per il carrello, scoperta del checkout, WBA, il ciclo lettura-aggiornamento-lettura, un riepilogo dell’ordine controllato dall’acquirente e il passaggio di controllo per le verifiche di pagamento. Il punto di partenza sono gli ordini in un singolo negozio e i percorsi Shop Pay con dati salvati.

Il limite è la distribuzione. I merchant non attivano Checkout WebMCP, ma agli acquirenti serve comunque un agente browser compatibile. B2B, checkout incorporato, SDK mobile, ordini tra più negozi e checkout ordinario in tre pagine senza Shop Pay restano esclusi dal percorso.

I limiti definiscono il prodotto

Checkout WebMCP è un’interfaccia più sicura per i checkout idonei nel browser, non un’API universale per gli acquisti.

Non può aggiungere o rimuovere articoli durante il checkout, acquisire il numero di una nuova carta, annullare il checkout, usare l’interfaccia definita dalle estensioni delle app né costringere un checkout escluso a registrare i tool. Non elimina l’accesso a Shop Pay, 3D Secure, le fasi di revisione o altre azioni richieste all’acquirente. Inoltre, non trasforma il testo del merchant in istruzioni affidabili per il modello.

La regola di progettazione più onesta è semplice: usare i tool finché sono registrati, considerare lo stato aggiornato come unica fonte attendibile e restituire la pagina all’acquirente ogni volta che il contratto richiede il suo intervento.

La mossa da fare lunedì

Lunedì, invece di distribuire le chiamate in tutto il codebase, conviene aggiungere all’agente un solo wrapper per il checkout. Al suo interno vanno riuniti serializzazione, corrispondenza dei tool, toolchange, navigazione con valore null, classificazione degli errori e lettura dello stato aggiornato. Poi si eseguono gli otto casi della fixture locale e si enumerano i risultati di document.modelContext.getTools() in un checkout di test idoneo e sotto il proprio controllo. Va provato un aggiornamento costruito a partire dallo stato appena letto. Il completamento è riservato a un ordine di test supportato e solo dopo una conferma esplicita; se non si dispone di un ordine di test sicuro, ci si ferma a ready_for_complete e si considera il completamento verificato dalle fonti, non testato in prima persona.

Se vuoi realizzare un agente commerciale che metta il consenso al centro, scopri il servizio di sviluppo di agenti AI.