Integraciones · preview

Carritos y checkout personalizado

El catálogo y el checkout son conexiones distintas. Una tienda puede consultar productos en WooCommerce y completar la compra en su propio frontend headless.

Estado y compatibilidad

• Catálogo WooCommerce + checkout nativo de WooCommerce: requiere verificación por instalación.
• Catálogo WooCommerce + checkout propio (por ejemplo un frontend headless): enlace firmado descrito en esta guía; la tienda implementa su receptor.
• Catálogo propio, Shopify, VTEX y Magento: lectores/adaptadores de este flujo pendientes. Tener sincronización o tracking no equivale a soporte de checkout.
• El contrato de transporte admite IDs opacos de otras plataformas; el borrador durable de esta entrega conserva IDs numéricos Woo. No se convierten ni inventan IDs para simular compatibilidad.

Azter prepara; la tienda conserva la compra

Azter mantiene la selección de la conversación, valida productos y cantidades y prepara un enlace. El receptor importa esa selección en el carrito de su tienda y conserva su checkout, promociones, despacho, impuestos, identidad, facturación y pagos.

Preparar o abrir el enlace no confirma compra, pedido, pago ni reserva de stock. Los pedidos siguen llegando por las integraciones de órdenes existentes. Reanudar un pedido con un token de pago es una operación distinta y no está incluida aquí.

Contrato versionado: azter.cart-handoff.v1

El comercio acuerda un endpoint HTTPS fijo bajo su control. Azter genera un enlace a ese endpoint con dos parámetros: cart y signature. Es una selección firmada, no una sesión Woo compartida. No requiere que Azter acceda al repositorio de la tienda.

1https://shop.example/checkout/import?cart=BASE64URL_PAYLOAD&signature=BASE64URL_HMAC

• La dirección del receptor es HTTPS, de un dominio público, sin puerto, sin parámetros ni #, y con una ruta distinta de «/».
• Queda dentro de la firma (endpoint_url): debe ser fija. Si cambia, se configura de nuevo y se vuelve a verificar.

Este es el JSON decodificado de un ejemplo sintético. Los IDs pertenecen al namespace acordado, nunca se deducen desde nombre o SKU. Para Woo, product_id es el padre y variant_id la variante exacta; los simples usan null.

1{
2  "protocol": "azter.cart-handoff.v1",
3  "audience": "merchant-prod",
4  "endpoint_url": "https://shop.example/checkout/import",
5  "key_id": "checkout-1",
6  "origin": "azter",
7  "selection_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8  "catalog_namespace": "woocommerce",
9  "issued_at": 1790791200,
10  "expires_at": 1790877600,
11  "cart_mode": "replace",
12  "items": [
13    {
14      "product_id": "61927",
15      "variant_id": "61928",
16      "quantity": 2
17    }
18  ]
19}

• audience identifica el destino acordado; endpoint_url vincula la firma al receptor exacto; key_id identifica la clave dedicada de esta conexión.
• selection_id es una referencia opaca estable del intento. No es un ID de pedido ni acredita quién abre el enlace.
• origin=azter permite atribuir la selección verificada. La apertura no es una venta y un enlace compartido no identifica al comprador.
• Sin nombres, precios, emails, teléfonos, RUT, cupones, credenciales ni tokens de pago en el payload.
• Hasta 50 líneas, cantidades 1–999 y URL completa de hasta 1800 caracteres. El tamaño puede limitar antes que las 50 líneas: se rechaza el exceso, nunca se trunca ni divide.
• cart_mode=replace: reemplazar, no sumar. IDs repetidos se rechazan. El plazo acordado es de 1 a 24 horas; el ejemplo usa 24 horas. No se renueva al reintentar.

Firma y seguridad

Usar una clave aleatoria dedicada de 32 bytes por conexión, representada como 64 caracteres hexadecimales en minúscula y compartida únicamente entre servidores. No reutilizar claves de Woo, Mercado Pago ni del conector de tracking. Nunca verificar HMAC en código enviado al navegador.

1cart = base64url(UTF8(JSON_del_payload)) // sin padding
2signature = base64url(HMAC_SHA256(
3  hex_decode(clave_dedicada),
4  UTF8("azter.cart-handoff.v1\n" + cart)
5)) // sin padding

El receptor verifica la firma sobre el parámetro cart exacto recibido: no reserializa JSON para verificar. Comparación constante, firma de 32 bytes y base64url canónico sin padding. Después valida el schema estricto y comprueba protocolo, audience, endpoint_url, key_id, namespace y modo contra configuración de servidor.

Rechazar issued_at futuro, expires_at vencido o un plazo distinto del acordado. Los IDs se tratan como datos, no como rutas ni SQL. No se aceptan destinos de redirección del payload. La selección no está cifrada: no introducir información privada.

La firma acredita procedencia, no autorización de pago. Un enlace válido puede reutilizarse hasta vencer. No hay revocación individual en V1; rotar o retirar la clave puede invalidar enlaces anteriores. Al recibirlo, usar Cache-Control: no-store y Referrer-Policy: no-referrer, quitar sus parámetros antes de cargar tracking y no registrar la URL completa.

Recepción, cambios e idempotencia

• 1. Verificar firma, destino, fechas y schema en el backend antes de cualquier cambio.
• 2. Resolver los productos del namespace y comprobar variantes, publicación, disponibilidad, precios actuales y restricciones de compra.
• 3. Validar todas las líneas antes de reemplazar el carrito. Ante un fallo, conservar el carrito anterior y explicar el problema; no quitar líneas ni reducir cantidades silenciosamente.
• 4. Importar con cantidades absolutas. Repetir el mismo enlace no añade dos veces; no usar selection_id para fusionar carritos de compradores distintos.
• 5. Crear únicamente el estado de carrito de ese navegador/sesión y llevarlo al checkout existente. No crear pedidos ni iniciar pagos desde este receptor.
• 6. Mostrar los productos y total final. Si hubo cambios, hacerlos visibles antes de que el cliente continúe con el flujo normal de compra.

1400 selección inválida / duplicados / parámetros repetidos\n401 firma inválida / destino incorrecto\n410 enlace vencido\n409 producto o variante no disponible / cantidad inválida\n503 no se pudo validar el catálogo\nNo redirigir silenciosamente al catálogo ni crear una selección parcial.

Vector de prueba

Generado con el firmador real y una clave pública de ejemplo que no se usa en ningún sistema. Sirve para validar el receptor antes de tener una clave propia: debe aceptar el enlace tal cual y rechazar las dos variantes.

1clave (solo para esta prueba) = 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
2audience = merchant-test · key_id = checkout-test · vigencia = 86400 s
3endpoint_url = https://shop.example/checkout/import
4
5cart = eyJhdWRpZW5jZSI6Im1lcmNoYW50LXRlc3QiLCJjYXJ0X21vZGUiOiJyZXBsYWNlIiwiY2F0YWxvZ19uYW1lc3BhY2UiOiJ3b29jb21tZXJjZSIsImVuZHBvaW50X3VybCI6Imh0dHBzOi8vc2hvcC5leGFtcGxlL2NoZWNrb3V0L2ltcG9ydCIsImV4cGlyZXNfYXQiOjE3OTA4Nzc2MDAsImlzc3VlZF9hdCI6MTc5MDc5MTIwMCwiaXRlbXMiOlt7InByb2R1Y3RfaWQiOiI2MTkyNyIsInF1YW50aXR5IjoyLCJ2YXJpYW50X2lkIjoiNjE5MjgifSx7InByb2R1Y3RfaWQiOiI3MDAwMSIsInF1YW50aXR5IjoxLCJ2YXJpYW50X2lkIjpudWxsfV0sImtleV9pZCI6ImNoZWNrb3V0LXRlc3QiLCJvcmlnaW4iOiJhenRlciIsInByb3RvY29sIjoiYXp0ZXIuY2FydC1oYW5kb2ZmLnYxIiwic2VsZWN0aW9uX2lkIjoiYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYSJ9
6signature = s_CstrORZFGZLRDjMar4uHjbOKzC4CeKundEx7r8N6o
7
8Con hora Unix 1790800000  → válido: 2 × variante 61928 del producto 61927, 1 × producto simple 70001
9Último carácter de signature cambiado → firma inválida (401)
10Con hora Unix 1790900000  → vencido (410)

Pruebas y activación por conexión

Antes de certificar el checkout: probar desde móvil y navegador anónimo una variante, varias líneas, cantidades, carrito previo, enlace repetido, enlace alterado, vencimiento, falta de stock y cambio de precio. Verificar RUT, boleta/factura, promociones y despacho sin enviar pedido ni pagar.

La conexión del catálogo no activa esta capacidad. El dueño o un administrador de la cuenta la configura en Azter, en la página de la tienda conectada:

• 1. Guardar la dirección del receptor y la vigencia del enlace. Azter genera la clave dedicada y la muestra una sola vez, junto con audience y key_id.
• 2. Entregar la clave al desarrollador por un canal seguro; va solo en el servidor de la tienda.
• 3. Generar enlaces de prueba firmados con la clave real para ejercitar el receptor, sin pasar por una conversación.
• 4. Cuando el receptor pasa las pruebas, marcarlo como verificado. La verificación queda ligada a esa dirección y esa clave: cambiar cualquiera de las dos obliga a verificar de nuevo.
• 5. Activar el módulo de carrito y asignar la capacidad al agente.

Azter no aloja el receptor: es parte de la tienda.