Tiendas para agentes de compradores

Cómo un agente de IA que compra por una persona (Claude, ChatGPT, Gemini) encuentra los productos de una tienda en Recaudo y le arma el carrito.

Activarlo

El negocio prende “Abrir mi tienda a agentes de IA” en Tienda en línea → Configuración. Mientras esté apagado, el MCP y el catálogo de la tienda responden 404. La ficha en las páginas de producto se publica siempre.

MCP de la tienda (Claude y otros clientes MCP)

Cada tienda tiene su propio servidor MCP público. No pide cuenta ni token porque es para el agente del comprador; el MCP de /mcp es otro, el del equipo del negocio.

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

Herramientas

• search_products Busca en el catálogo por texto o categoría. Regresa productos con existencia, precio con impuestos, link e imagen.
• get_product Detalle de un producto: descripción, imágenes y presentaciones con su precio.
• create_cart_link Arma un link que abre el carrito de la tienda con esos productos. El agente se lo da a la persona, que revisa y 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 en formato ChatGPT

El catálogo completo en JSON Lines, con los campos del feed de productos de ChatGPT (Agentic Commerce Protocol). Para aparecer en ChatGPT Shopping, OpenAI tiene que dar de alta la tienda; este archivo es lo que se les entrega. Solo incluye productos activos con foto y precio.

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

Ficha en cada página de producto

Cada página de producto trae un bloque schema.org Product en JSON-LD: nombre, imágenes, precio con impuestos, moneda, existencia y vendedor. Lo leen los agentes que navegan (Claude, Gemini, Perplexity) y también Google.

Checkout desde el chat (Agentic Commerce Protocol)

Para que ChatGPT u otra plataforma compre sin mandar a la persona a la tienda. La plataforma abre una sesión con los ids del catálogo (SKU o id del producto), Recaudo pone precios, impuestos y envío desde la tienda, y al completar crea el pedido y cobra el token de pago de un solo uso.

• POST /checkout_sessions Abre la sesión (201).
• POST /checkout_sessions/{id} Cambia productos, comprador o dirección.
• GET /checkout_sessions/{id} Consulta la sesión.
• POST /checkout_sessions/{id}/complete Crea el pedido y cobra.
• POST /checkout_sessions/{id}/cancel Cancela; una sesión completada 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"
    }
}

Autenticación con Authorization: Bearer y la llave que el negocio genera en Tienda en línea → Configuración (se muestra una vez). Cada POST lleva Idempotency-Key: el mismo cuerpo regresa la misma respuesta; otro cuerpo con la misma llave responde 422 idempotency_conflict y una petición que sigue en curso, 409 idempotency_in_flight.

Montos enteros en centavos y moneda en minúsculas. Se aceptan items [{id, quantity}] y line_items [{item: {id, quantity}}]. La sesión queda ready_for_payment cuando hay correo del comprador, dirección (si la tienda la pide) y todo está disponible; si no, not_ready_for_payment con mensajes por campo. El pago es un Shared Payment Token de Stripe (spt_…) que se cobra con la cuenta de Stripe del negocio; si lo rechazan responde 402 payment_declined, el pedido se cancela, el inventario regresa y la sesión acepta otro token.

Si el negocio guarda la URL de avisos y el secreto que le da la plataforma, Recaudo manda order_created al completar y order_updated en cada cambio del pedido, con el encabezado Merchant-Signature (HMAC-SHA256 del cuerpo, en hex) y Timestamp. Estados: created, confirmed, shipped, fulfilled, canceled. Con checkout activo y términos y aviso de privacidad configurados, el catálogo marca is_eligible_checkout.

Mandatos AP2 (v0.2)

Para agentes que usan AP2 (FIDO Alliance): la persona firma qué carrito autoriza y la tienda lo verifica antes de cobrar. Es opcional; si no llega mandato, el checkout funciona igual.

1. Cuando la sesión está en ready_for_payment, la respuesta trae ap2.checkout_jwt: el carrito (productos, cantidades, moneda y total) firmado por la tienda con ES256, y ap2.jwks_uri con su llave pública.
2. El agente arma el mandato de checkout (SD-JWT mandate.checkout.1) con ese checkout_jwt, su checkout_hash (SHA-256 en base64url) y la llave de la persona en el encabezado jwk y en cnf.jwk, más un KB-JWT con sd_hash y aud igual a la URL de complete.
3. Lo manda en ap2.checkout_mandate al completar. Recaudo revisa firmas, divulgaciones, hash, fechas y que el carrito siga igual. Si algo no cuadra responde 400 invalid_mandate y no cobra.
4. Al cobrar, la respuesta trae ap2.checkout_receipt: un JWT firmado por la tienda con status Success, reference (el checkout_hash) y order_id. Si el cobro se rechaza, el recibo dice Error.

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

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