ChatGPT Merchants e a jornada do merchant: do registro às responsabilidades

1. O que é um ChatGPT‑merchant e em que ele difere de uma “loja comum”

Do ponto de vista de quem desenvolve, é muito fácil confundir os níveis: temos um app Next.js, um servidor MCP, algum commerce backend, e em algum lugar ainda OpenAI, ChatGPT, Stripe e outros serviços “gente grande”. Dá vontade de dizer: “É tudo um sistema só; o importante é o teste ficar verde”.

Mas no mundo do AI‑commerce, as fronteiras jurídicas e técnicas são bem separadas. O ChatGPT não vira sua loja e não se transforma em processador de pagamentos. Ele apenas fornece uma interface inteligente e chama suas APIs por especificações abertas. O merchant continua sendo uma empresa concreta, com um catálogo concreto e responsabilidade perante o usuário.

Entender o papel do merchant não é só para o jurídico. Disso dependem decisões de arquitetura: onde ficam os dados do feed, como você valida pedidos, o que você registra em logs, como depura divergências entre o que foi mostrado no chat e o que realmente ocorreu no seu sistema.

Exemplo

Vamos imaginar um e‑commerce clássico: você tem um site, carrinho, checkout, integração com um provedor de pagamentos. O usuário entra no navegador, clica, digita os dados do cartão — tudo claro.

O ChatGPT‑merchant é a mesma loja, só que capaz de vender por um diálogo com IA, com alto grau de automação. A diferença não está no o quê você vende, e sim em como o como o usuário percorre o caminho do pedido até o pagamento.

Do ponto de vista da OpenAI, o merchant é uma organização (ou pessoa física empreendedora) que:

• fornece um Product Feed pela especificação da OpenAI (CSV/TSV/XML/JSON com dados estruturados sobre SKUs);
• se cadastra no portal ChatGPT Merchants e passa pela verificação de categorias e requisitos legais;
• na versão avançada, implementa Agentic Checkout e Delegated Payment para que o Instant Checkout no ChatGPT consiga concluir o pagamento sem sair para o seu site.

Ou seja, o merchant não é “a pessoa que escreveu um widget”, mas o dono do sortimento e dos compromissos financeiros. No nosso curso, jogamos dois papéis: a equipe que escreve o GiftGenius como ChatGPT App e a equipe que faz o backend do merchant que atende esse App.

2. Portal ChatGPT Merchants: do pedido até virar merchant em produção

A OpenAI tem um site separado para vendedores — o portal ChatGPT Merchants. Por ele, os vendedores entram no programa Instant Checkout e conectam seus feeds e backend. Vamos destrinchar esse caminho em etapas, ainda sem detalhes técnicos profundos (isso fica para a próxima aula).

Preparação prévia

Antes de alguém do seu time clicar em “Apply”, vocês já precisam ter algumas peças:

Entidade jurídica e site. O merchant tem um domínio e uma vitrine (storefront) compreensível para o usuário — mesmo que depois tudo seja vendido pelo ChatGPT, a OpenAI espera que exista uma vitrine pública.

Sortimento dentro da política. Na aula anterior falamos da Prohibited Products Policy: não pode, por exemplo, armas ou certos itens médicos. Qualquer produto que você queira vender pelo ChatGPT deve se encaixar na lista de categorias permitidas.

Infraestrutura básica de pagamentos. Embora o Delegated Payment tire de você a necessidade de lidar diretamente com cartões, você deve ter integração com um PSP (como o Stripe) e entender como criar pedidos e reembolsos no seu sistema.

Pedido no portal Merchants

Tecnicamente é um passo meio sem graça, mas importante: você entra no site e solicita participação no programa Instant Checkout. Normalmente perguntam:

• quem é você (pessoa jurídica, site, contatos);
• o que você vende (categorias, faixa de preços, regiões);
• de que forma você vai fornecer o Product Feed (formato, URL, periodicidade de atualização).

Essa parte tem pouca relação com TypeScript, mas impacta muito o seu roadmap: enquanto o merchant não passar na verificação básica, o Instant Checkout não será ativado, mesmo que seu código esteja perfeito.

Conexão do Product Feed

Depois que avaliarem seu pedido e concordarem em geral, o foco técnico principal se desloca para o Product Feed. Pela documentação, o feed é obrigatório: sem ele o ChatGPT simplesmente não sabe o que você vende.

Nesta etapa você:

1. Define o formato do feed (quase sempre CSV ou JSON).
2. Combina como vai disponibilizá‑lo: pode ser um pre‑signed URL no S3 ou um endpoint HTTPS para onde você envia atualizações por POST periodicamente.
3. Prepara o mínimo de campos para cada SKU: id, title, description, price, currency, availability, link, imagens e flags enable_search / enable_checkout.

Enquanto você definir enable_checkout = false, o merchant pode operar em modo apenas de descoberta (discovery‑only): o ChatGPT encontra e recomenda produtos, mas ao tentar comprar, envia o usuário para o seu site.

Integração ACP (mais detalhes na próxima aula)

Quando o Product Feed estiver estável e você quiser avançar, começa a integração de Agentic Checkout e Delegated Payment. Do ponto de vista do portal Merchants, é um bloco de requisitos à parte: é preciso implementar os endpoints /checkout_sessions, aprender a aceitar o token de pagamento delegado (Shared Payment Token) e concluir as sessões corretamente com os status necessários (not_ready_for_payment, ready_for_payment, completed, canceled).

Nesta aula, falamos disso só como “o próximo nível de dificuldade”. Todos os detalhes de protocolo e esquemas de requisição veremos na próxima aula.

3.5. Certificação e ativação do Instant Checkout

A etapa final é verificar como seu backend se comporta em cenários reais:

• os pedidos são criados corretamente;
• os preços do feed batem com os preços pelos quais você realmente cobra;
• os erros e reembolsos são tratados corretamente;
• suas páginas de ToS/Privacy atendem às expectativas da OpenAI e da legislação local.

Depois disso, o merchant recebe o status “pronto para Instant Checkout” e os seus produtos com enable_checkout = true passam a ser realmente compráveis diretamente no ChatGPT.

Tudo isso pode ser imaginado como um diagrama simples:

flowchart TD
  A[Há produto e site] --> B[Solicitação no ChatGPT Merchants]
  B --> C[Product Feed conectado]
  C --> D["ACP backend implementado
(checkout_sessions + delegated payment)"]
  D --> E[Certificação
e ativação do Instant Checkout]

3. Variações de merchant: Etsy/Shopify vs backend customizado

Boa notícia: nem todos os merchants precisam escrever todo o backend ACP. Para algumas plataformas (Shopify, Etsy etc.) já existem integrações que assumem a implementação técnica.

Se você vende pelo Shopify ou Etsy, o esquema é mais ou menos assim: você ativa uma opção do tipo “Show in ChatGPT” e a plataforma por si só:

• gera e mantém o Product Feed no formato necessário;
• implementa ou faz proxy dos endpoints ACP;
• conecta com o Stripe ou outro PSP.

Você, como dono da loja, foca mais no sortimento e nas descrições do que em endpoints REST.

Se, como no nosso curso com o GiftGenius, você está construindo um merchant customizado com backend próprio, terá muito mais liberdade, mas também mais trabalho: você escreve o código que implementa o feed, o checkout e a integração com o provedor de pagamentos.

É útil comparar isso em uma tabela:

Para o curso escolhemos conscientemente a terceira opção: só assim conseguimos percorrer todo o caminho do feed até os webhooks e um produção confiável.

4. Responsabilidades do merchant: dados, pedidos, política, dinheiro

Ao virar um ChatGPT‑merchant, você assume não só a alegria dos novos pedidos, mas também um conjunto bem concreto de obrigações. Vamos por camadas.

Dados de catálogo e qualidade do Product Feed

O Product Feed é a fonte da verdade para o ChatGPT. Se nele consta que um produto custa 10 USD e está disponível, é isso que o usuário verá no chat. Se o feed mentir, no melhor dos casos você terá um cliente insatisfeito; no pior, violação de política e problemas com a OpenAI.

Espera‑se do merchant:

• correção dos campos obrigatórios (formato correto de preço, códigos ISO de moedas, links HTTPS válidos, imagens que funcionam);
• atualização do feed com frequência suficiente para não vender produto “fantasma”;
• consistência de identificadores: o id do SKU no feed deve bater com o ID na sua base e no sistema de pedidos, para você entender sem ambiguidade o que exatamente foi comprado.

Fazendo um paralelo com e‑commerce comum, aqui o Product Feed é o seu “export para marketplace”, só que o marketplace, neste caso, não é um site, e sim um assistente inteligente que “mora” na cabeça do usuário e lembra fácil das inconsistências.

Pedidos, entrega e devoluções

O ChatGPT não vira a sua central de suporte. O usuário até conversa com ele, mas juridicamente compra o produto do merchant, não da OpenAI. Portanto:

• você responde por o pedido ser criado no seu sistema e chegar ao estoque;
• você responde por o envio chegar ao endereço indicado pelo usuário no Instant Checkout;
• você responde por processar devoluções, cancelamentos, reembolsos parciais etc.

No âmbito do ACP, checkout_session, após a conclusão bem‑sucedida, normalmente contém um objeto order com seus campos. Mas isso é apenas o reflexo do que ocorreu no seu backend — é você quem decide como é o registro na tabela orders, quais status existem e como se relacionam com a logística.

Política e geografia

No portal Merchants você indica em quais países vende e quais tipos de produtos. A OpenAI, por sua vez, verifica se você:

• não vende categorias proibidas;
• cumpre a legislação local (por exemplo, regras fiscais e restrições etárias);
• fornece Terms of Service e Privacy Policy compreensíveis.

Nos módulos seguintes falaremos mais sobre páginas jurídicas, mas já agora é útil pensar assim: “Se eu não conseguir explicar ao jurídico o que vendo e onde, o ChatGPT dificilmente vai vender isso por mim”.

Dinheiro e provedor de pagamento

Por fim, o mais assustador — dinheiro. Felizmente, ACP e Delegated Payment simplificam bastante a vida de quem desenvolve:

• o ChatGPT e o provedor de pagamentos (por exemplo, Stripe) combinam um Shared Payment Token para um valor e merchant específicos;
• seu backend recebe esse token na requisição complete e o usa no seu PSP, sem ver dados “crus” de cartão.

Ou seja, você não vira um monstro compatível com PCI, não armazena números de cartão e não mergulha em auditorias. Sua responsabilidade é usar corretamente o token delegado (criar o pagamento, capturar valores, fazer reembolso) e manter a contabilidade com cuidado.

5. Como isso se encaixa na arquitetura do GiftGenius

Voltando ao nosso app didático GiftGenius. Em termos de arquitetura, depois do módulo 14 queremos que a pessoa aluna consiga desenhar um esquema do tipo: “Usuário → ChatGPT → App widget → MCP Gateway → Product Feed / Agents / ACP backend”.

Nesse esquema, o papel de merchant é implementado no nosso backend, enquanto o widget e o App são apenas a “face” desse merchant no ChatGPT.

Configuração do merchant no código

Comecemos com um passo simples: vamos criar no código uma estrutura de configuração do merchant. Que seja um módulo TypeScript lib/merchantConfig.ts no nosso projeto Next.js:

// lib/merchantConfig.ts
export type MerchantConfig = {
  id: string;                // ID do merchant no ACP/Stripe
  name: string;              // Nome legível por humanos
  feedUrl: string;           // Onde está localizado o 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, // vamos ativar depois
};

Aqui, primeiro, fixamos explicitamente os limites: isto é um merchant, não um “widget”. Segundo, extraímos valores importantes para variáveis de ambiente — nos módulos sobre deploy e ambientes ainda vamos lembrar por que não se deve hardcodear esse tipo de coisa.

Para conveniência, podemos adicionar uma função simples que diga ao nosso código se já é possível usar o Instant Checkout:

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

Assim, preparamos a arquitetura para comportamentos diferentes por ambiente e evitamos que nós (e o GPT) entremos por engano em um checkout real a partir de um ambiente de testes.

MCP‑tool para obter informações do merchant

Muitas vezes é útil dar à modelo e ao widget a capacidade de saber em que modo o merchant está operando. Por exemplo, para o GPT não oferecer Instant Checkout se ele estiver desativado.

No servidor MCP (que levantamos nos módulos anteriores) podemos criar uma ferramenta simples:

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

export const getMerchantInfoTool = {
  name: "get_merchant_info",
  description: "Retorna informações básicas sobre o merchant GiftGenius",
  inputSchema: { type: "object", properties: {}, additionalProperties: false },
  async handler() {
    return {
      id: giftGeniusMerchant.id,
      name: giftGeniusMerchant.name,
      instantCheckout: canUseInstantCheckout(giftGeniusMerchant),
    };
  },
};

Essa ferramenta não faz nada extraordinário, mas cria um ponto explícito onde a modelo pode perguntar: “Dá para comprar direto no chat agora ou apenas seguir o link?”.

Uso das informações do merchant no widget

No lado do widget, usando os hooks já conhecidos do Apps SDK, podemos chamar get_merchant_info e mudar o UI conforme o modo. Um exemplo simples de 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>
  );
}

Esse componente pequeno realça para o usuário (e para você em modo dev) em que estado a integração com o ChatGPT está no momento.

6. Mini‑desafio prático

Para a aula não ficar só no nível de “palavras e diagramas”, tente realizar os passos abaixo no seu projeto GiftGenius (ou semelhante):

Primeiro, adicione um módulo de configuração do merchant, parecido com merchantConfig.ts, e extraia MERCHANT_ID e PRODUCT_FEED_URL para variáveis de ambiente. Para desenvolvimento local, use .env.local; para produção, as configurações da Vercel ou de outra plataforma.

Depois, implemente no servidor MCP uma ferramenta simples get_merchant_info, que retorne ao menos name e instantCheckout. Pense em quais outros campos podem ser úteis para a modelo: por exemplo, a lista de moedas suportadas ou países de entrega.

Em terceiro lugar, adicione no widget um pequeno elemento de UI (badge, linha de status, legenda no card do produto) que use essa ferramenta e mostre ao usuário em que modo seu merchant opera agora: apenas recomendações ou já com Instant Checkout completo. Isso não é só útil para UX, mas também ajuda muito na depuração.

Por fim, tente escrever em texto quais passos o seu projeto específico seguirá desde “temos site e backend” até o status de ChatGPT‑merchant. Onde exatamente você vai conectar o Product Feed, quando vai ativar o enable_checkout, quando vai começar a implementação dos endpoints ACP. Esse exercício disciplina bem e ajuda a não esquecer coisas importantes e pouco amadas, como a política de devoluções.

7. Erros típicos no caminho para virar ChatGPT‑merchant

Erro nº 1: “O ChatGPT é a minha loja”.
Às vezes, quem desenvolve “move” mentalmente tudo para o lado do ChatGPT: como se ele guardasse o catálogo, calculasse preços e executasse pedidos. Na realidade, o ChatGPT é interface e orquestrador, não seu ERP. Se esquecer isso, é fácil construir uma arquitetura sem um modelo próprio de pedidos, onde todos os dados vivem “perdidos em prompts”, e qualquer mudança no comportamento do modelo ameaça a consistência.

Erro nº 2: esperar Instant Checkout sem cadastro separado e sem ACP.
O fato de você ter escrito um ótimo widget e configurado o Product Feed não liga automaticamente o Instant Checkout. É preciso solicitar no portal Merchants, passar verificação de categorias, implementar Agentic Checkout e Delegated Payment, e passar nos testes. Tentar contar com o Instant Checkout “por padrão” geralmente termina com o GPT oferecendo ao usuário algo que não existe de verdade — ou entregando links no lugar de telas de pagamento esperadas.

Erro nº 3: hardcode de IDs e URLs do merchant.
História clássica: MERCHANT_ID = "prod-123" fica gravado direto no código, o URL do feed — como string em um componente do widget. Assim que surge um staging ou a necessidade de criar um segundo merchant, começa a busca e substituição em massa. É muito mais seguro extrair essas coisas para configuração e variáveis de ambiente, e usá‑las por uma camada pequena de abstração, como fizemos com MerchantConfig.

Erro nº 4: o Product Feed “vive sua própria vida”, desconectado dos pedidos.
Se no feed o SKU GIFT_RED_MUG custa 10 USD, mas na base de pedidos para o mesmo identificador você, por algum motivo, cobra 12 USD, cedo ou tarde isso vai aparecer. A fonte da verdade sobre preço e disponibilidade deve ser ou o feed (montado a partir dos seus dados internos) ou uma camada comum em que tanto o feed quanto o checkout confiem. Tentar manter “dupla contabilidade” (uma para o ChatGPT, outra para o seu site) dá problema rapidamente.

Erro nº 5: ignorar o papel do provedor de pagamentos e o armazenamento de dados de pagamento.
Às vezes surge a tentação de “espiar” dentro do token do provedor de pagamentos, ou até pedir dados de pagamento do usuário no seu UI. Isso não só quebra o modelo de Delegated Payment, como pode arrastar você para o mundo do PCI DSS e um compliance pesado. A prática correta é tratar o Shared Payment Token como uma string opaca, usá‑lo apenas no SDK do provedor de pagamentos e nunca logar nem fazer cache.

Erro nº 6: subestimar as muitas etapas do onboarding e a falta de um plano.
Por fim, um erro organizacional comum é pensar “vamos só nos conectar ao ChatGPT, não tem mistério”. Na prática, a jornada do merchant é feita de muitas etapas: técnicas (feed, backend, testes) e não técnicas (documentos jurídicos, aprovação de categorias, restrições regionais). Se você não escrever esse caminho com antecedência, o time vai pular caoticamente entre tarefas, e os prazos vão “derreter” mais rápido do que o seu entusiasmo com AI‑commerce.