Confirmación de compra incorporada

La integración de la confirmación de compra incorporada permite que tu confirmación de compra basada en la Web se incorpore en las plataformas de Google. Usa esta ruta si tu producto requiere una lógica compleja (p.ej., personalizaciones) que la API nativa no puede admitir. Implementarás una IU de confirmación de compra que se incorporará en el flujo de confirmación de compra a través de un iframe.

¿Qué es la confirmación de compra incorporada?

La confirmación de compra integrada (EC) permite que un host (como la Búsqueda de Google o un agente de IA) muestre tu confirmación de compra existente basada en la Web dentro de su aplicación (con un iframe o una WebView). A diferencia de un redireccionamiento web estándar, esto permite la comunicación bidireccional. El host puede "delegar" tareas específicas, como seleccionar una dirección guardada o pagar con una credencial almacenada, para brindar una experiencia más rápida y nativa, mientras que tú sigues siendo el comerciante oficial y te encargas de la creación del pedido.

Lista de tareas para la implementación del comercio

Para admitir la pantalla de confirmación de la compra integrada, debes implementar los siguientes requisitos en tu API de UCP y en tu aplicación de confirmación de la compra de frontend.

1. Habilita la detección (API de UCP)

Debes declarar que tu proceso de confirmación de compra admite la extensión integrada en las respuestas de la API de UCP.

  • Acción: Agrega el objeto de capacidad dev.ucp.shopping.embedded_checkout al array de capacidades de respuesta de la UCP.
  • Requisito: Incluye las URLs de especificaciones y esquemas.
  • Opcional: Si necesitas autenticación (p.ej., un token JWT) para cargar la confirmación de compra, establece auth.required como verdadero.
"capabilities": [
  {
    "name": "dev.ucp.shopping.embedded_checkout",
    "version": "2026-01-11",
    "spec": "https://ucp.dev/specs/shopping/embedded_checkout",
    "config": {
        "auth": { "required": true }
    }
  }
]

2. Controla la inicialización de la URL (frontend)

Cuando el host cargue tu continue_url, agregará parámetros de búsqueda específicos. Tu frontend debe analizar estos datos inmediatamente después de la carga.

  • Acción: Analiza los siguientes parámetros de consulta de URL:
    • ec_version: Es la versión del protocolo (p.ej., 2026-01-11).
    • ec_auth: (Si corresponde) Valida el token de autorización proporcionado por el host si configuraste auth.required: true.
    • ec_delegate: Es una lista separada por comas de las acciones que el host desea controlar de forma nativa (p.ej., payment.credential, fulfillment.address_change, payment.instruments_change).

3. Establece la comunicación (frontend)

La comunicación se produce a través de postMessage con el formato JSON-RPC 2.0.

  • Acción: Implementa un objeto de escucha para los eventos message.
  • Requisito: Debes validar el origen de cada mensaje para asegurarte de que coincida con el host.
  • Compatibilidad nativa: En el caso de los hosts de apps nativas, verifica y utiliza las variables globales insertadas (p.ej., window.EmbeddedCheckoutProtocolConsumer) si postMessage no está disponible.

4. Realiza el handshake (frontend)

En cuanto se renderice la confirmación de compra, debes indicarle al host que estás listo y confirmar qué delegaciones aceptas.

  • Acción: Envía la solicitud ec.ready inmediatamente después de la carga.
  • Carga útil: Incluye un array delegate que enumera las capacidades que aceptas que controle el host.
  • Ejemplo: Si la URL solicitada es ec_delegate=payment.credential y la aceptas, incluye "payment.credential" en la carga útil de ec.ready.
// Example: Sending the ec.ready message
const hostWindow = window.parent;
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "ready_1",
  "method": "ec.ready",
  "params": {
    "delegate": ["payment.credential"] // List capabilities you accept to delegate
  }
}), "*");

5. Implementa la lógica de delegación (frontend)

Si aceptaste una delegación en el saludo, debes modificar el comportamiento de tu IU para evitar conflictos.

  • Acción: Oculta los elementos de la IU pertinentes para las tareas delegadas.
  • Ejemplo: Si fulfillment.address_change está delegado, oculta tu formulario de dirección y muestra un botón "Cambiar dirección" en su lugar.
  • Acción: Cuando el usuario haga clic en ese botón, envía un mensaje _request (p.ej., ec.fulfillment.address_change_request) al host.
  • Acción: Espera la respuesta del organizador. La respuesta contendrá los datos nuevos (p.ej., la dirección seleccionada).
  • Requisito: Actualiza el estado de la confirmación de compra con un reemplazo de estilo PUT (reemplaza toda la sección del objeto) según los datos que devuelve el host.
// Example: requesting payment credential
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "req_1",
  "method": "ec.payment.credential_request",
  "params": {
      "checkout": currentCheckoutState // Pass the full current checkout object
  }
}), "*");

6. Envía actualizaciones de estado y ciclo de vida (frontend)

Debes mantener al host informado sobre el estado de la confirmación de compra para que pueda actualizar su IU o controlar los errores.

  • Action: Envía notificaciones (mensajes sin un ID) cuando cambia el estado:
    • ec.start: Cuando la confirmación de compra es completamente visible.
    • ec.line_items.change: Indica si se actualizó el contenido o los totales del carrito.
    • ec.buyer.change: Si se actualizan los detalles del comprador
    • ec.complete: Cuando se realiza el pedido correctamente.
    • ec.error: Si se produce un error crítico.

7. Aplicar la seguridad (servidor/encabezados)

Debes asegurarte de que los actores maliciosos no puedan incorporar tu proceso de confirmación de compra.

  • Acción: Implementa encabezados de la Política de Seguridad del Contenido (CSP).
  • Requisito: Establece frame-ancestors <host_origin>; para permitir la incorporación solo en hosts de confianza.
  • Navegación: Bloquea la lógica que aleja al usuario del flujo de confirmación de compra (p.ej., quita los vínculos de "Seguir comprando" que dirigen a tu página principal). Se permiten excepciones para la verificación 3DS o los redireccionamientos de pagos de terceros.