Conecta tu tienda a Ubi

Entrega con Ubi en tu checkout

1. En el portal de Ubi, entra a Ajustes → Integraciones → «Entrega con Ubi en tu checkout». Crea la clave pública y agrega la dirección de tu tienda (con https). El componente solo funciona en esos sitios.

2. Pega esto en tu página de pago, donde va el envío:

<div data-ubi-key="pk_live_…" data-ubi-order="ORDEN-123" data-ubi-sizes="M"></div>
<script src="https://checkout.ubi.pa/embed/v1.js" async></script>

Quien compra ve tres opciones. Locker o punto: la lista de los lugares donde cabe el paquete y que tu comercio puede usar; no hace falta dirección. A domicilio: pide la dirección en tu formulario, como siempre; después le escribimos por WhatsApp para el pin exacto y el día. Usar Mi Ubi: se abre una ventana de Mi Ubi, elige una dirección guardada y el día (o su locker de siempre) y la ventana se cierra. Tú no ves esa dirección.

Cuando elige, el elemento recibe el evento ubi:change y, si está dentro de un formulario, se agrega el campo oculto ubi_checkout_session con el id de la sesión.

document.querySelector("[data-ubi-key]").addEventListener("ubi:change", (e) => {
  // e.detail: { session_id, choice: "locker" | "door" | "saved", locker, delivery_date }
});

Con locker o Mi Ubi, no le pidas la dirección: tu formulario la puede dejar opcional. Prueba todo en la tienda de prueba.

Crear la orden

Desde tu servidor, con tu clave secreta, crea la orden con el id de la sesión. Lo que eligió quien compra manda sobre el destino.

curl -X POST https://api.ubi.pa/v1/orders \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: ORDEN-123" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "ORDEN-123",
    "checkout_session": "ID-DE-LA-SESION",
    "recipient": { "name": "Ana Pérez", "phone": "6123-4567", "email": "ana@correo.com" },
    "address": "Calle 50, edificio Sol, apto 3B",
    "packages": [{ "size": "M" }]
  }'

Con locker, va a ese lugar. Con Mi Ubi, usamos su dirección y el día que eligió (y su teléfono comprobado): tú solo ves que va a domicilio. A domicilio sin Mi Ubi, usamos la dirección que mandas. Para saber qué eligió antes de crear la orden:

curl https://api.ubi.pa/v1/checkout/sessions/ID-DE-LA-SESION -H "Authorization: Bearer sk_live_…"
# { "status": "chosen", "choice": "locker", "locker": { "name": "…", "address": "…" }, "mi_ubi": null }

El primer contacto con quien compra

A domicilio sin Mi Ubi, la orden trae confirm_url: el link donde la persona pone el pin de su puerta y elige el día. Tu tienda es una marca conocida, así que es mejor que el primer contacto salga de ti: ponlo en la página de gracias, en el correo de confirmación del pedido o en tu propio WhatsApp. Si la persona lo abre ahí, nosotros no le escribimos; si no lo abre, se lo mandamos por WhatsApp de Ubi con el mismo link. Después, todo lo de la entrega lo atendemos nosotros.

{ "id": "…", "number": 1042, "confirm_url": "https://mi.ubi.pa/c/AbC123", "packages": [ … ] }

WooCommerce, Shopify y sin tienda en línea

WooCommerce: instala el plugin «Entregas Ubi», pega tu clave de API y tu clave pública, y agrega el método de envío «Entrega con Ubi» en tus zonas de envío. El plugin muestra el componente, deja la dirección opcional con locker o Mi Ubi, crea la orden con la sesión y pone el botón «Confirma tu entrega» en la página de gracias y en el correo.

Shopify: conecta la tienda en el portal (Integraciones → Tiendas en línea) y cada orden pagada entra sola. Para el componente, la sesión tiene que llegar como atributo del carrito ubi_checkout_session. Qué deja agregar Shopify en el checkout depende del plan de la tienda (por verificar con cada tienda); mientras tanto, el método de envío «Locker CÓDIGO» y el atributo ubi_locker siguen funcionando.

Sin tienda en línea (Instagram, WhatsApp): crea la orden en el portal con el teléfono de quien compra. Nosotros le pedimos la dirección por WhatsApp, igual que siempre.

La API y los avisos

La referencia completa (órdenes, paquetes, lockers, errores, límites y avisos firmados) está en la documentación de la API. La dirección base es https://api.ubi.pa/v1.