ChatGPT Merchants e il percorso del merchant: dalla registrazione alle responsabilità

1. Chi è il merchant ChatGPT e in cosa differisce da «un negozio tradizionale»

Dal punto di vista di uno sviluppatore è molto facile confondere i livelli: abbiamo un'applicazione Next.js, un server MCP, un qualche backend commerce, e da qualche parte ci sono anche OpenAI, ChatGPT, Stripe e altri servizi “adulti”. Verrebbe da dire: «È tutto un unico grande sistema, l'importante è che i test siano verdi».

Ma nel mondo dell'AI‑commerce i confini giuridici e tecnici sono rigidamente separati. ChatGPT non diventa il vostro negozio e non si trasforma in un processore di pagamenti. Fornisce solo un'interfaccia intelligente e chiama le vostre API tramite specifiche aperte. Il merchant rimane una specifica azienda con un catalogo concreto e responsabilità dirette verso l'utente.

Capire il ruolo del merchant non serve solo ai legali. Da questo dipendono le decisioni architetturali: dove sono conservati i dati del feed, come validate gli ordini, cosa loggate, come fate debug delle discrepanze tra ciò che viene mostrato in chat e ciò che è realmente accaduto nel vostro sistema.

Esempio

Immaginiamo un e‑commerce classico: avete un sito, un carrello, un checkout, l'integrazione con un provider di pagamento. L'utente entra dal browser, clicca con il mouse, inserisce i dati della carta — tutto chiaro.

Un merchant ChatGPT è lo stesso negozio, solo che ha imparato a vendere tramite un dialogo con l'IA con un alto grado di automazione. La differenza non è in cosa vendete, ma in come l'utente percorre il tragitto dalla richiesta al pagamento.

Dal punto di vista di OpenAI, un merchant è un'organizzazione (o un lavoratore autonomo) che:

• fornisce un Product Feed secondo la specifica di OpenAI (CSV/TSV/XML/JSON con dati strutturati sugli SKU);
• si registra nel portale ChatGPT Merchants e supera la verifica delle categorie e dei requisiti legali;
• nella variante avanzata implementa Agentic Checkout e Delegated Payment, così che Instant Checkout in ChatGPT possa effettuare il pagamento senza uscire sul vostro sito.

Cioè un merchant non è «una persona che ha scritto un widget», ma il proprietario dell'assortimento e degli obblighi finanziari. Nel nostro corso giochiamo due ruoli contemporaneamente: siamo sia il team che sviluppa GiftGenius come ChatGPT App, sia il team che realizza il backend del merchant che serve questa App.

2. Portale ChatGPT Merchants: percorso dalla candidatura al merchant in produzione

OpenAI ha un sito separato per i venditori — il portale ChatGPT Merchants. Attraverso di esso i venditori entrano nel programma Instant Checkout e collegano i propri feed e backend. Analizziamo questo percorso a passi, senza dettagli tecnici profondi (saranno nella prossima lezione).

Preparazione preliminare

Prima che qualcuno del vostro team prema il pulsante «Apply», dovreste già avere alcuni mattoncini pronti:

Entità legale e sito. Il merchant ha un dominio e uno storefront comprensibile per l'utente — anche se poi tutto verrà venduto tramite ChatGPT, OpenAI si aspetta che esista una vetrina pubblica.

Assortimento in linea con la policy. Nella lezione precedente abbiamo parlato della Prohibited Products Policy: non sono consentite, ad esempio, armi o alcuni prodotti medicali. Qualsiasi articolo che volete vendere tramite ChatGPT deve rientrare nell'elenco delle categorie ammesse.

Infrastruttura di pagamento di base. Anche se Delegated Payment vi solleva dalla necessità di lavorare direttamente con le carte, dovete avere un'integrazione con un PSP (ad esempio Stripe) e sapere come create ordini e rimborsi nel vostro sistema.

Domanda nel portale Merchants

Dal punto di vista tecnico è un passaggio piuttosto noioso ma importante: accedete al sito e presentate la candidatura per partecipare al programma Instant Checkout. Di solito chiedono:

• chi siete (persona giuridica, sito, contatti);
• cosa vendete (categorie, fascia di prezzo, regioni);
• in che modo siete pronti a fornire il Product Feed (formato, URL, periodicità degli aggiornamenti).

Questa parte è poco legata a TypeScript, ma influisce molto sulla vostra roadmap: finché il merchant non ha superato la verifica di base, nessun Instant Checkout verrà attivato, anche se il vostro codice è perfetto.

Collegamento del Product Feed

Dopo che la candidatura è stata esaminata e approvata in linea generale, il focus tecnico principale si sposta sul Product Feed. Secondo la documentazione, il feed è obbligatorio per l'integrazione: senza di esso ChatGPT semplicemente non sa cosa vendete.

In questo passaggio voi:

1. Definite il formato del feed (più spesso CSV o JSON).
2. Concordate come fornirlo: può essere un URL pre‑firmato su S3 o un endpoint HTTPS a cui inviate periodicamente aggiornamenti via POST.
3. Preparate il minimo di campi per ogni SKU: id, title, description, price, currency, availability, link, immagini e flag enable_search / enable_checkout.

Finché impostate enable_checkout = false, il merchant può operare in modalità discovery‑only: ChatGPT trova e raccomanda i prodotti, ma al tentativo di acquisto manda l'utente sul vostro sito.

Integrazione ACP (dettagli nella prossima lezione)

Quando il Product Feed è stabile e siete pronti a proseguire, inizia l'integrazione di Agentic Checkout e Delegated Payment. Dal punto di vista del portale Merchants è un blocco di requisiti separato: bisogna implementare gli endpoint /checkout_sessions, imparare a ricevere il token di pagamento delegato (Shared Payment Token) e concludere correttamente le sessioni con gli stati necessari (not_ready_for_payment, ready_for_payment, completed, canceled).

In questa lezione ne parliamo solo come del «livello di difficoltà successivo». Tutti i dettagli del protocollo e gli schemi delle richieste li vedremo nella prossima lezione.

3.5. Certificazione e attivazione di Instant Checkout

Fase conclusiva — verifica di come il vostro backend si comporta in scenari reali:

• se gli ordini vengono creati correttamente;
• se i prezzi del feed coincidono con i prezzi a cui addebitate realmente il denaro;
• se gli errori e i rimborsi vengono gestiti correttamente;
• se le vostre pagine ToS/Privacy sono in linea con le aspettative di OpenAI e della normativa locale.

Dopo di ciò il merchant ottiene lo stato «pronto per Instant Checkout» e i suoi prodotti con enable_checkout = true diventano effettivamente acquistabili direttamente in ChatGPT.

Tutto questo si può immaginare come un semplice diagramma:

flowchart TD
  A[Esistono prodotto e sito] --> B[Candidatura in ChatGPT Merchants]
  B --> C[Product Feed collegato]
  C --> D["Backend ACP implementato
(checkout_sessions + delegated payment)"]
  D --> E[Certificazione
e attivazione di Instant Checkout]

3. Varianti di merchant: Etsy/Shopify vs backend personalizzato

Buona notizia: non tutti i merchant sono obbligati a scrivere da soli l'intero backend ACP. Per alcune piattaforme (Shopify, Etsy e altre) esistono già integrazioni che si occupano della parte tecnica.

Se vendete tramite Shopify o Etsy, lo schema è più o meno questo: attivate da loro un'opzione tipo «Show in ChatGPT», e la piattaforma stessa:

• forma e mantiene il Product Feed nel formato richiesto;
• implementa o fa da proxy agli endpoint ACP;
• si collega a Stripe o a un altro PSP.

Voi, come proprietari del negozio, vi occupate più dell'assortimento e delle descrizioni che degli endpoint REST.

Se invece, come nel nostro corso con GiftGenius, costruite un merchant personalizzato con un vostro backend, avete molta più libertà ma anche più lavoro: scrivete voi stessi il codice che implementa il feed, il checkout e l'integrazione con il provider di pagamento.

È comodo confrontarlo in una tabella:

Per il corso scegliamo consapevolmente la terza opzione: solo così possiamo percorrere l'intero cammino dal feed ai webhook e fino a un'affidabile produzione.

4. Responsabilità del merchant: dati, ordini, policy, denaro

Quando diventate un merchant ChatGPT, non firmate solo per la gioia dei nuovi ordini, ma anche per un set di obblighi molto concreti. Analizziamoli per livelli.

Dati di catalogo e qualità del Product Feed

Il Product Feed è la fonte di verità per ChatGPT. Se in esso è indicato che un prodotto costa 10 USD ed è disponibile, è esattamente questo che vedrà l'utente in chat. Se il feed mente, nel migliore dei casi otterrete un cliente scontento, nel peggiore — una violazione della policy e problemi con OpenAI.

Dal merchant ci si aspetta:

• correttezza dei campi obbligatori (formato del prezzo corretto, codici ISO delle valute, link HTTPS validi, immagini funzionanti);
• aggiornamenti del feed abbastanza frequenti, per non vendere prodotti fantasma;
• consistenza degli identificatori: l'id dello SKU nel feed deve coincidere con l'ID nel vostro database e nel sistema degli ordini, in modo da poter capire univocamente cosa è stato acquistato.

Facendo un parallelo con l'e‑commerce tradizionale, qui il Product Feed è il vostro «export verso il marketplace», solo che in questo caso il marketplace non è un sito, ma un assistente intelligente che vive nella testa dell'utente e ricorda facilmente le incongruenze.

Ordini, spedizione e rimborsi

ChatGPT non diventa l'assistenza clienti del vostro negozio. L'utente, certo, interagisce con lui, ma giuridicamente acquista il prodotto dal merchant, non da OpenAI. Dunque:

• siete responsabili della creazione dell'ordine nel vostro sistema e del suo arrivo al magazzino;
• siete responsabili che la spedizione arrivi all'indirizzo indicato dall'utente in Instant Checkout;
• siete responsabili della gestione di resi, annullamenti, rimborsi parziali, ecc.

Nel contesto ACP, checkout_session dopo il completamento con successo di solito contiene un oggetto order con i propri campi. Ma è solo il riflesso di ciò che è avvenuto nel vostro backend — siete voi a decidere come appare la riga nella tabella orders, quali stati esistono, come sono collegati alla logistica.

Policy e geografia

Nel portale Merchants indicate in quali Paesi vendete e quali tipi di prodotti. Dal canto suo, OpenAI verifica che voi:

• non vendiate categorie proibite;
• rispettiate la normativa locale (ad esempio regole fiscali e restrizioni di età);
• forniate Termini di Servizio e Privacy Policy chiari.

Nei moduli successivi parleremo ancora delle pagine legali, ma già ora è utile pensare in termini: «Se non riesco a spiegare a un legale cosa vendo e dove, difficilmente ChatGPT lo venderà per me».

Denaro e provider di pagamento

Infine, la parte più delicata — il denaro. Per fortuna, ACP e Delegated Payment semplificano molto la vita degli sviluppatori:

• ChatGPT e il provider di pagamento (ad esempio Stripe) concordano uno Shared Payment Token per un importo e un merchant specifici;
• il vostro backend riceve questo token nella richiesta complete e lo usa nel proprio PSP, senza vedere dati «grezzi» della carta.

Quindi non vi trasformate in un mostro conforme al PCI, non memorizzate numeri di carta e non finite negli incubi degli audit. La vostra responsabilità è usare correttamente il token delegato (creare il pagamento, addebitare il denaro, effettuare il rimborso) e tenere una contabilità accurata.

5. Come si applica all'architettura di GiftGenius

Torniamo alla nostra app didattica GiftGenius. A livello architetturale, dopo il modulo 14 vogliamo che lo studente sappia disegnare uno schema del tipo: «Utente → ChatGPT → App widget → MCP Gateway → Product Feed / Agents / backend ACP».

In questo schema il ruolo del merchant è implementato nel nostro backend, mentre il widget e l'App sono solo il «volto» di questo merchant in ChatGPT.

Configurazione del merchant nel codice

Iniziamo con un passaggio semplice: creiamo nel codice una struttura di configurazione del merchant. Supponiamo sia un modulo TypeScript lib/merchantConfig.ts nel nostro progetto Next.js:

// lib/merchantConfig.ts
export type MerchantConfig = {
  id: string;                // ID del merchant in ACP/Stripe
  name: string;              // Nome leggibile
  feedUrl: string;           // Dove si trova il Product Feed
  instantCheckoutEnabled: boolean;
};

export const giftGeniusMerchant: MerchantConfig = {
  id: process.env.MERCHANT_ID ?? "dev-merchant",
  name: "GiftGenius",
  feedUrl: process.env.PRODUCT_FEED_URL ?? "https://example.com/feed.json",
  instantCheckoutEnabled: false, // lo abiliteremo più tardi
};

Qui, in primo luogo, fissiamo esplicitamente i confini: questo è il merchant, non un «widget». In secondo luogo, estraiamo valori importanti nelle variabili d'ambiente — nei moduli sul deploy e sugli ambienti torneremo più volte sul perché non conviene hardcodare tali cose.

Per comodità si può aggiungere una semplice funzione che dica al nostro codice se ora è possibile usare Instant Checkout:

// lib/merchantConfig.ts
export function canUseInstantCheckout(cfg: MerchantConfig) {
  // In dev e staging disattiviamo sempre Instant Checkout
  if (process.env.NODE_ENV !== "production") return false;
  return cfg.instantCheckoutEnabled;
}

Così prepariamo in anticipo l'architettura al fatto che in ambienti diversi il comportamento sarà diverso e impediamo a noi stessi (e a GPT) di finire accidentalmente in un checkout di produzione da uno staging di test.

Strumento MCP per ottenere informazioni sul merchant

Spesso è utile dare al modello e al widget la possibilità di sapere in quale modalità sta operando il merchant. Ad esempio, per evitare che GPT proponga Instant Checkout se è disattivato.

Nel server MCP (che abbiamo avviato nei moduli precedenti) si può creare un semplice strumento:

// mcp/tools/merchant.ts
import { giftGeniusMerchant, canUseInstantCheckout } from "../lib/merchantConfig";

export const getMerchantInfoTool = {
  name: "get_merchant_info",
  description: "Restituisce le informazioni di base sul merchant GiftGenius",
  inputSchema: { type: "object", properties: {}, additionalProperties: false },
  async handler() {
    return {
      id: giftGeniusMerchant.id,
      name: giftGeniusMerchant.name,
      instantCheckout: canUseInstantCheckout(giftGeniusMerchant),
    };
  },
};

Questo strumento non fa nulla di incredibile, ma crea un punto esplicito in cui il modello può chiedere: «Si può acquistare direttamente in chat oppure solo seguire un link?».

Uso delle informazioni sul merchant nel widget

Dal lato del widget, usando le hook dell'Apps SDK che già conosciamo, si può chiamare get_merchant_info e cambiare la UI in base alla modalità. Un esempio minimale di componente:

// components/MerchantBadge.tsx
"use client";

import { useEffect, useState } from "react";
import { useCallTool } from "../lib/use-call-tool";

type MerchantInfo = { name: string; instantCheckout: boolean };

export function MerchantBadge() {
  const callTool = useCallTool();
  const [info, setInfo] = useState<MerchantInfo | null>(null);

  useEffect(() => {
    callTool("get_merchant_info", {}).then((res) => {
      setInfo(res?.result as MerchantInfo);
    });
  }, [callTool]);

  if (!info) return null;
  return (
    <span>
      {info.name} · {info.instantCheckout ? "Instant Checkout" : "Discovery only"}
    </span>
  );
}

Un piccolo componente del genere sottolinea piacevolmente all'utente (e a voi stessi in modalità dev) in quale stato si trovi attualmente l'integrazione con ChatGPT.

6. Mini esercizio pratico

Per evitare che la lezione rimanga solo a livello di «parole e diagrammi», provate a eseguire i seguenti passi nel vostro progetto GiftGenius (o analogo):

Per prima cosa, aggiungete un modulo di configurazione del merchant, simile a merchantConfig.ts, ed estraete MERCHANT_ID e PRODUCT_FEED_URL nelle variabili d'ambiente. Per lo sviluppo locale potete usare .env.local, e per la produzione — le impostazioni di Vercel o di un'altra piattaforma.

In secondo luogo, implementate nel server MCP un semplice strumento get_merchant_info che ritorni almeno name e instantCheckout. Pensate a quali altri campi potrebbero essere utili al modello: ad esempio, l'elenco delle valute supportate o dei Paesi di spedizione.

In terzo luogo, aggiungete nel widget un piccolo elemento di UI (badge, riga di stato, etichetta sulla scheda prodotto) che usi questo tool e mostri all'utente in quale modalità sta operando ora il vostro merchant: solo raccomandazioni o già un Instant Checkout completo. Non è solo utile per la UX, ma aiuta molto anche nel debug.

Infine, provate a descrivere per iscritto con quali passi il vostro progetto specifico passerà da «abbiamo un sito e un backend» allo stato di merchant ChatGPT. Dove collegherete esattamente il Product Feed, quando attiverete enable_checkout, quando inizierete l'implementazione degli endpoint ACP. Un esercizio del genere disciplina bene e aiuta a non dimenticare cose importanti ma poco amate come la policy sui resi.

7. Errori tipici nel percorso verso il merchant ChatGPT

Errore n. 1: «ChatGPT è il mio negozio».
A volte gli sviluppatori «spostano» mentalmente tutto sul lato ChatGPT: come se fosse lui a conservare il catalogo, calcolare i prezzi ed evadere gli ordini. In realtà ChatGPT è un'interfaccia e un orchestratore, non il vostro ERP. Se lo si dimentica, è facile costruire un'architettura in cui non esiste un proprio modello degli ordini, tutti i dati vivono «da qualche parte nei prompt» e qualsiasi cambiamento nel comportamento del modello minaccia la consistenza.

Errore n. 2: aspettarsi Instant Checkout senza registrazione separata e ACP.
Il fatto che abbiate scritto un ottimo widget e configurato il Product Feed non attiva automaticamente Instant Checkout. Servono la candidatura nel portale Merchants, la verifica delle categorie, l'implementazione di Agentic Checkout e Delegated Payment, il superamento dei test. Cercare di basarsi su Instant Checkout «di default» di solito finisce con GPT che propone all'utente qualcosa che in realtà non c'è, o che fornisce link al posto delle attese schermate di pagamento.

Errore n. 3: hardcoding rigido di identificatori e URL del merchant.
Storia classica: MERCHANT_ID = "prod-123" è scritto direttamente nel codice, l'URL del feed — una stringa nel componente del widget. Appena avete uno staging o la necessità di creare un secondo merchant, inizia la sostituzione massiva cerca‑e‑sostituisci. Molto più sicuro estrarre queste cose in configurazione e variabili d'ambiente e usarle tramite un piccolo strato di astrazione, come abbiamo fatto con MerchantConfig.

Errore n. 4: il Product Feed vive una vita propria, scollegata dagli ordini.
Se nel feed lo SKU GIFT_RED_MUG costa 10 USD e nel database degli ordini per lo stesso identificatore per qualche motivo addebitate 12 USD, prima o poi verrà a galla. La fonte di verità su prezzi e disponibilità deve essere o il feed, generato dai vostri dati interni, o uno strato comune a cui si affidano sia il feed sia il checkout. Tentare una «doppia contabilità» (una per ChatGPT, un'altra per il vostro sito) porta molto velocemente a problemi.

Errore n. 5: ignorare il ruolo del provider di pagamento e la conservazione dei dati di pagamento.
A volte sorge la tentazione di «sbirciare» nel token del provider di pagamento o addirittura di chiedere ulteriori dati di pagamento all'utente nella vostra UI. Non solo questo viola il modello di Delegated Payment, ma può trascinarvi nel mondo del PCI DSS e del pesante compliance. La prassi corretta è trattare lo Shared Payment Token come una stringa opaca, usarlo solo nell'SDK del provider di pagamento e non loggarlo né metterlo in cache da nessuna parte.

Errore n. 6: sottovalutare la multistep dell'onboarding e l'assenza di un piano.
Infine, un errore organizzativo frequente — pensare che «tanto ci colleghiamo a ChatGPT, cosa ci sarà mai di complicato». In realtà il percorso del merchant è composto da molti passi: tecnici (feed, backend, test) e non tecnici (documenti legali, approvazione delle categorie, restrizioni regionali). Se non si pianifica questo percorso in anticipo, il team salterà caoticamente tra le attività e le scadenze inizieranno a «sciogliersi» più velocemente dell'entusiasmo per l'AI‑commerce.