Botón de Xip para checkouts

"Autocompletar con Xip" va en la página de pago de una tienda o de una pasarela (como PagueloFácil). El comprador pone su celular, aprueba en su WhatsApp cuál dirección compartir, y el checkout recibe la dirección con el pin exacto, cómo entrar y el código Xip. Sin escribirla.

Cómo funciona

1. La tienda pega un <div> y un <script> donde va la dirección.
2. El comprador toca Autocompletar con Xip. Se abre una ventana de Xip encima del checkout.
3. Pone su celular. Xip le manda un WhatsApp con un link. Si está comprando desde ese mismo celular, también puede elegir ahí mismo.
4. En el link elige una dirección guardada o crea una nueva con el pin, y la aprueba. También puede decir que no la comparte.
5. La ventana se cierra y el checkout muestra la tarjeta Dirección aprobada.
6. El servidor de la tienda pide la dirección completa con su clave secreta.

Mientras el WhatsApp de Xip no esté encendido, el paso 3 abre la elección en una ventana nueva, sin WhatsApp.

1. Activarlo

En el panel de negocio: Conectar tu sistema → Botón en tu checkout → Activar el botón.

• Sitios donde va el botón: uno por línea (tutienda.com). El botón no funciona en otros sitios.
• Código para pegar: el panel lo da con tu clave pública (xip_pk_…). La clave pública puede ir en el navegador: sola no da acceso a ninguna dirección.

2. Pegar el botón

<div data-xip-key="xip_pk_…" data-xip-order="ORDEN-123" data-xip-name="Ana"></div>
<script src="https://xip.com.pa/embed/v1.js" async></script>

O desde JavaScript:

Xip.mount("#xip", {
  publicKey: "xip_pk_…",
  orderRef: "ORDEN-123",
  onApproved(r) { /* r.requestId, r.approvedBy, r.label, r.line */ },
  onDeclined() { /* el comprador no compartió su dirección */ },
});

Cuando el comprador aprueba:

• el elemento dispara el evento xip:approved, con detail.requestId, detail.label y detail.line;
• si el botón está dentro de un <form>, se agrega el campo oculto xip_address_request_id.

El navegador solo recibe lo necesario para mostrar la tarjeta (tipo y calle). El pin, cómo entrar y el resto nunca pasan por la página.

3. Pedir la dirección desde tu servidor

Con el xip_address_request_id y tu clave secreta (la de Claves de API):

curl https://api.xip.com.pa/v1/address-requests/$ID \
  -H "Authorization: Bearer $XIP_API_KEY"

La respuesta trae status: "approved" y address con el pin (location), la calle, cómo entrar, notas, código Xip y el link para que el motorizado llegue. Tienes acceso por 14 días; cada lectura queda registrada. También puedes recibirla al momento por webhook (address_request.approved). Detalle en API.md.

WooCommerce

Hay un plugin: integrations/woocommerce/xip-checkout (el .zip instalable se arma con zip -r dist/xip-checkout-1.0.0.zip xip-checkout dentro de integrations/woocommerce).

• Pone el botón en el checkout clásico y en el de bloques.
• Al aprobar, llena la calle; al crear el pedido, pide la dirección completa con la clave secreta y la guarda: la calle y cómo entrar en la dirección de envío; el pin, el código Xip y el link para el motorizado en el pedido y en sus notas.
• Ajustes en WooCommerce → Ajustes → Integración → Xip (clave pública y clave secreta).
• Probado en WordPress 7.1 con WooCommerce 11.2, en los dos checkouts.

Para probarlo sin una tienda: WordPress Playground levanta un WordPress local con el plugin montado.

npx --yes @wp-playground/cli@3.1.59 server --port=9400 --login \
  --blueprint=woo-blueprint.json \
  --mount=integrations/woocommerce/xip-checkout:/wordpress/wp-content/plugins/xip-checkout

El blueprint instala WooCommerce, crea un producto, envío gratis y pago contra entrega, y guarda las claves en woocommerce_xip_settings con base_url apuntando al Xip local. En el negocio de prueba, el sitio permitido es http://127.0.0.1:9400. El blueprint lleva claves: va fuera del repo y se borra al terminar.

Pasarelas de pago (PagueloFácil)

La pasarela pega el botón una sola vez en su checkout y le llega a todos sus comercios. Hay dos formas de hacerlo:

• La pasarela como un solo negocio en Xip. La pasarela usa su propia clave, recibe la dirección aprobada y se la pasa al comercio con la orden. Es lo más simple para empezar.
• Cada comercio con su clave. La pasarela pone en el botón la clave pública del comercio que cobra. Así cada comercio ve sus direcciones en su panel de Xip.

En Shopify, la página de pago de PagueloFácil llega después de que Shopify ya pidió la dirección. Ahí el botón sirve para confirmar el pin exacto y cómo entrar, no para llenar la dirección.

Límites

• 10 pedidos cada 10 minutos por IP, y 3 cada 10 minutos al mismo número.
• 500 por hora por tienda.
• El pedido vence a las 24 horas si nadie lo aprueba.

Para probar en desarrollo

/dev/tienda?key=xip_pk_… es una tienda de prueba que pega el botón igual que una tienda real. No existe en producción.