Lojas para agentes de compradores

Como um agente de IA que compra por uma pessoa (Claude, ChatGPT, Gemini) encontra os produtos de uma loja no Recaudo e monta o carrinho.

Ativar

O negócio liga “Abrir minha loja a agentes de IA” em Loja online → Configurações. Enquanto estiver desligado, o MCP e o catálogo da loja respondem 404. A marcação nas páginas de produto é publicada sempre.

MCP da loja (Claude e outros clientes MCP)

Cada loja tem seu próprio servidor MCP público. Não pede conta nem token porque é para o agente do comprador; o /mcp é outro servidor, o da equipe do negócio.

https://recaudo.app/store/{slug}/mcp

Ferramentas

• search_products Busca no catálogo por texto ou categoria. Retorna produtos em estoque com preço com impostos, link e imagem.
• get_product Detalhe de um produto: descrição, imagens e apresentações com seu preço.
• create_cart_link Monta um link que abre o carrinho da loja com esses produtos. O agente entrega à pessoa, que revisa e paga.

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "search_products",
        "arguments": {
            "query": "café",
            "limit": 5
        }
    }
}

{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "create_cart_link",
        "arguments": {
            "items": [
                {
                    "product_id": "…",
                    "quantity": 2,
                    "tier_label": "Caja de 6"
                }
            ]
        }
    }
}

Catálogo no formato do ChatGPT

O catálogo completo em JSON Lines, com os campos do feed de produtos do ChatGPT (Agentic Commerce Protocol). Para aparecer no ChatGPT Shopping, a OpenAI precisa cadastrar a loja; este arquivo é o que você entrega. Só entram produtos ativos com foto e preço.

https://recaudo.app/store/{slug}/agent-feed.jsonl

Marcação em cada página de produto

Cada página de produto traz um bloco schema.org Product em JSON-LD: nome, imagens, preço com impostos, moeda, estoque e vendedor. Os agentes que navegam (Claude, Gemini, Perplexity) leem, e o Google também.

Checkout pelo chat (Agentic Commerce Protocol)

Para que o ChatGPT ou outra plataforma compre sem mandar a pessoa para a loja. A plataforma abre uma sessão com os ids do catálogo (SKU ou id do produto), o Recaudo define preços, impostos e frete pela loja e, ao concluir, cria o pedido e cobra o token de pagamento de uso único.

• POST /checkout_sessions Abre a sessão (201).
• POST /checkout_sessions/{id} Altera produtos, comprador ou endereço.
• GET /checkout_sessions/{id} Consulta a sessão.
• POST /checkout_sessions/{id}/complete Cria o pedido e cobra.
• POST /checkout_sessions/{id}/cancel Cancela; uma sessão concluída responde 405.

https://recaudo.app/acp/{slug}/checkout_sessions

{
    "items": [
        {
            "id": "SKU-123",
            "quantity": 2
        }
    ],
    "buyer": {
        "first_name": "Ana",
        "last_name": "López",
        "email": "ana@example.com"
    },
    "fulfillment_address": {
        "name": "Ana López",
        "line_one": "Av. Reforma 1",
        "city": "CDMX",
        "state": "CDMX",
        "country": "MX",
        "postal_code": "06600"
    }
}

{
    "payment_data": {
        "token": "spt_…",
        "provider": "stripe"
    }
}

Autenticação com Authorization: Bearer e a chave que o negócio gera em Loja online → Configuração (mostrada uma vez). Todo POST leva Idempotency-Key: o mesmo corpo devolve a mesma resposta; outro corpo com a mesma chave responde 422 idempotency_conflict e uma requisição ainda em andamento, 409 idempotency_in_flight.

Valores inteiros em centavos e moeda em minúsculas. São aceitos items [{id, quantity}] e line_items [{item: {id, quantity}}]. A sessão fica ready_for_payment quando há e-mail do comprador, endereço (se a loja pedir) e tudo está disponível; senão, not_ready_for_payment com mensagens por campo. O pagamento é um Shared Payment Token da Stripe (spt_…) cobrado com a conta Stripe do negócio; se recusado responde 402 payment_declined, o pedido é cancelado, o estoque volta e a sessão aceita outro token.

Se o negócio salvar a URL de avisos e o segredo que a plataforma fornece, o Recaudo envia order_created ao concluir e order_updated a cada mudança do pedido, com o cabeçalho Merchant-Signature (HMAC-SHA256 do corpo, em hex) e Timestamp. Status: created, confirmed, shipped, fulfilled, canceled. Com checkout ativo e termos e política de privacidade configurados, o catálogo marca is_eligible_checkout.

Mandatos AP2 (v0.2)

Para agentes que usam AP2 (FIDO Alliance): a pessoa assina qual carrinho autoriza e a loja verifica antes de cobrar. É opcional; sem mandato o checkout funciona igual.

1. Quando a sessão está em ready_for_payment, a resposta traz ap2.checkout_jwt: o carrinho (produtos, quantidades, moeda e total) assinado pela loja com ES256, e ap2.jwks_uri com sua chave pública.
2. O agente monta o mandato de checkout (SD-JWT mandate.checkout.1) com esse checkout_jwt, seu checkout_hash (SHA-256 em base64url) e a chave da pessoa no cabeçalho jwk e em cnf.jwk, mais um KB-JWT com sd_hash e aud igual à URL de complete.
3. Envia em ap2.checkout_mandate ao concluir. O Recaudo confere assinaturas, divulgações, hash, datas e que o carrinho continua igual. Se algo não bater responde 400 invalid_mandate e não cobra.
4. Ao cobrar, a resposta traz ap2.checkout_receipt: um JWT assinado pela loja com status Success, reference (o checkout_hash) e order_id. Se a cobrança for recusada, o recibo diz Error.

https://recaudo.app/store/{slug}/jwks.json

{
    "payment_data": {
        "token": "spt_…",
        "provider": "stripe"
    },
    "ap2": {
        "checkout_mandate": "<issuer-jwt>~<disclosure>~…~<kb-jwt>"
    }
}