Puntos de recogida en tiendas headless y apps móviles
El widget del carrito de Globe funciona dentro de un tema de Shopify. Una app móvil nativa basada en la Storefront API, o una tienda web headless como Hydrogen o Next.js, no tiene ningún tema donde colocarlo. Esta guía explica cómo pueden elegir los compradores de esas apps un punto de recogida antes de llegar al checkout de Shopify.
Las dos opciones siguientes guardan el punto en el carrito de la Storefront API como atributos del carrito. A partir de ahí, el checkout y el procesamiento del pedido tratan el punto exactamente igual que uno elegido en el widget del carrito.
Elija una opción
Sección titulada «Elija una opción»| A: Página de selección alojada | B: Storefront API de puntos de recogida | |
|---|---|---|
| Qué construye usted | Abrir una URL en un WebView, una ventana emergente o un iframe | Su propio mapa o lista, en la interfaz de su app |
| Interfaz | El mapa, la lista, la búsqueda, la geolocalización y el filtro de transportistas de Globe | La suya |
| Quién escribe en el carrito | Globe | Su app, con cartAttributesUpdate |
| Credencial | Ninguna. La página funciona en el dominio de su tienda | Una clave publicable (glb_pk_…) |
| Qué gestiona su app | Abrir la página y leer el resultado | La ubicación, la búsqueda, la lista de puntos y la escritura en el carrito |
Empiece por la A si quiere que funcione rápido. Elija la B cuando el selector deba verse y comportarse como un componente nativo de su app. Puede cambiar más adelante: las dos escriben los mismos atributos del carrito.
Antes de empezar
Sección titulada «Antes de empezar»- Globe está instalado y tiene un plan activo.
- Los puntos de recogida headless están activados para su tienda. Los activamos tienda por tienda: pídalo en el chat de soporte de la app. Hasta entonces, Configuración → Aplicaciones headless y móviles solo muestra Solicitar acceso, y tanto la página de selección como la Storefront API de puntos de recogida responden que la función no está activada.
- Hay al menos un transportista de puntos de recogida configurado y asignado a métodos de envío. Consulte Añadir transportistas de puntos de recogida.
- Su app crea carritos con la Storefront API y envía a los compradores al
checkoutUrldel carrito.
Configurar Globe
Sección titulada «Configurar Globe»En el panel de Globe, vaya a Configuración → Aplicaciones headless y móviles.
Para la página de selección alojada
Sección titulada «Para la página de selección alojada»- En Página de selección de punto de recogida, haga clic en Activar.
- En URL de retorno, haga clic en Añadir URL de retorno y añada todas las direcciones a las que la página pueda devolver a los compradores:
- un enlace profundo de la app, por ejemplo
myapp://pickup, - un universal link o un Android App Link, por ejemplo
https://app.example.com/pickup, - una dirección web de su tienda headless, por ejemplo
https://shop.example.com/cart.
- un enlace profundo de la app, por ejemplo
- Haga clic en Guardar en la barra de guardado.
Las URL de retorno son opcionales si su app lee el resultado solo mediante un puente nativo o postMessage. Son obligatorias para las redirecciones, y los orígenes web para postMessage se toman de las URL de retorno https. Consulte Return URLs.
Si la tarjeta indica que Globe necesita los permisos de carrito de la tienda, abra Globe una vez desde su panel de control de Shopify y apruebe los permisos actualizados. Hasta entonces, la página muestra que la selección no está disponible.
Para la Storefront API de puntos de recogida
Sección titulada «Para la Storefront API de puntos de recogida»- En Storefront API de puntos de recogida, haga clic en Crear clave y copie la clave publicable.
- Opcional: en Orígenes web permitidos, haga clic en Añadir origen y añada los orígenes de su tienda web, por ejemplo
https://shop.example.com. Si no hay ningún origen en la lista, cualquier sitio web puede usar la clave. Las apps nativas nunca se ven afectadas. - Haga clic en Guardar en la barra de guardado.
Una clave publicable solo busca los puntos de recogida de sus transportistas, así que puede incluirse sin riesgo en una app o en el código JavaScript de una web. Consulte Authentication.
Opción A: página de selección alojada
Sección titulada «Opción A: página de selección alojada»-
Cree o cargue el carrito del comprador con la Storefront API y guarde su
id. -
Abra esta URL en el dominio de su tienda:
https://{shop domain}/apps/appfleece-globe/select?cart={URL-encoded cart id}&return_url={allowlisted URL}&state={your value} -
El comprador elige un punto. Globe lo verifica con el transportista y escribe los atributos del carrito.
-
Su app recibe el resultado: una redirección a
return_url, un mensaje del puente nativo opostMessage. -
Vuelva a consultar el carrito y continúe hacia el
checkoutUrl.
Los parámetros completos, los mensajes de resultado y el código para iOS, Android, React Native e Hydrogen están en Hosted selection page.
Opción B: Storefront API de puntos de recogida
Sección titulada «Opción B: Storefront API de puntos de recogida»- Pida la ubicación del comprador o deje que mueva un mapa.
- Busque:
GET https://api-globe.appfleece.app/v1/storefront/pickup-points?country=CZ&latitude=…&longitude=…con la cabeceraX-Globe-Publishable-Key. - Muestre los puntos. Cuando el comprador elija uno, tome sus
cart_attributes. - Combínelos con los atributos que ya tiene el carrito y escriba la lista con la mutación
cartAttributesUpdatede la Storefront API. - Continúe hacia el
checkoutUrl.
Los endpoints y el código para curl, Swift, Kotlin, TypeScript e Hydrogen están en Storefront pickup API.
El contrato de atributos del carrito
Sección titulada «El contrato de atributos del carrito»Las dos opciones terminan con estos atributos en el carrito:
| Clave | Valor |
|---|---|
globe_PickupPointId | El ID del punto |
globe_PickupPointName | El nombre del punto |
globe_PickupPointAddress | La dirección en una sola línea |
globe_PickupPointData | El punto completo como cadena JSON |
globe_DeliveryMethod | pickup |
globe_PickupPointCustomerId | El Postnummer de DHL; si no, vacío |
Escriba los cart_attributes completos, exactamente como los devuelve la Storefront API de puntos de recogida. Globe admite enviar solo globe_PickupPointId como alternativa, y únicamente para las redes de transportistas que Globe almacena por su cuenta: con los transportistas que Globe consulta en tiempo real, como GLS o DHL, un ID por sí solo no se puede verificar y el punto no se guarda en el pedido.
Cuando el comprador cambie a entrega a domicilio, elimine del carrito las claves del punto. Cart attributes contiene el contrato completo, la alternativa con solo el ID y lo que hay que escribir para la entrega a domicilio.
Qué ocurre en el checkout
Sección titulada «Qué ocurre en el checkout»El checkout lee los atributos del carrito mediante la personalización del envío de Globe, si la activó en Configuración → Widget del carrito → Personalización del envío en checkout:
- Solo siguen visibles las tarifas de envío del transportista del punto seleccionado.
- Si allí configuró el cambio de nombre de las tarifas, la tarifa muestra el nombre del punto.
- Si el comprador cambia en el checkout el país de entrega a uno en el que no está el punto, el checkout muestra todas las tarifas como de costumbre.
Con la página de selección alojada y Rellenado de dirección en checkout activado, el checkout también se abre con la dirección del punto como dirección de entrega. El comprador puede cambiarla de todos modos. La Storefront API de puntos de recogida no toca la dirección de entrega.
Qué ocurre al crearse el pedido
Sección titulada «Qué ocurre al crearse el pedido»Cuando Shopify crea el pedido, Globe lee los atributos del carrito y verifica el punto con la red del transportista. Esto se aplica a todos los canales, incluido el widget del carrito del tema.
| Resultado | Qué hace Globe |
|---|---|
| El punto existe y está activo | Sustituye el nombre, la dirección y las coordenadas del punto por los datos del transportista, lo guarda en el pedido (metafield Globe.PickupPoint) y aplica las etiquetas de pedido, los atributos de pedido y la nota del transportista |
| El punto no se encuentra, está inactivo, es de otro país o de un transportista no asignado al método de envío del pedido, o el método de envío no es una tarifa de punto de recogida | No guarda ningún punto. El pedido recibe la etiqueta de pedido Falta punto de recogida (por defecto point_unselected) si ha configurado una, y se aplica el flujo de recordatorios habitual |
| No se puede contactar con el transportista | Conserva tal cual el punto de globe_PickupPointData del carrito |
El carrito solo tenía globe_PickupPointId y Globe no pudo verificarlo (siempre ocurre con los transportistas que Globe consulta en tiempo real, como GLS o DHL) | No guarda ningún punto y aplica la etiqueta de pedido sin punto seleccionado |
Las etiquetas de envío, las exportaciones y las integraciones con ERP o WMS ven los mismos campos que en los pedidos de su tienda online. Consulte Metafield del punto de recogida.
Solución de problemas
Sección titulada «Solución de problemas»La página muestra «Pickup point selection is not enabled for this shop.» Active la página en Configuración → Aplicaciones headless y móviles. Si esa sección solo muestra Solicitar acceso, los puntos de recogida headless aún no están activados para su tienda. Pídalo en el chat de soporte.
La Storefront API de puntos de recogida responde 403 access_required con «Headless pickup is not enabled for this shop.»
La función se activa tienda por tienda. Pídalo en el chat de soporte. Una clave creada antes empezará a funcionar en cuanto se active la función.
La página muestra «This cart no longer exists.» El carrito ha caducado, ya se ha convertido en un pedido o pertenece a otra tienda. Cree un carrito nuevo y vuelva a abrir la página.
La página muestra «This return address is not allowed for this shop.»
return_url no empieza por ninguna de sus URL de retorno. Compruebe el esquema, el host y la ruta. Un subdominio no cuenta como coincidencia.
La página muestra «Pickup point selection is temporarily unavailable.» Globe no tiene un plan activo, o no se aprobaron los permisos de carrito de la tienda. Abra Globe desde su panel de control de Shopify.
La página pide una contraseña. La tienda online está protegida con contraseña, como las tiendas de desarrollo. Introduzca la contraseña de la tienda una vez en el mismo WebView o navegador.
El pedido no tiene punto de recogida.
Compruebe si el pedido tiene su etiqueta de pedido sin punto seleccionado. Después compruebe que el carrito tenía globe_PickupPointData antes del checkout, que el comprador eligió una tarifa de punto de recogida del mismo transportista y que el país de entrega coincide con el del punto.
La API responde 403 origin_not_allowed.
Añada el origen del sitio web en Orígenes web permitidos, o elimine todos los orígenes para permitir cualquier sitio web.
La API responde 429 rate_limited para todos los compradores.
Su servidor llama a la API para todos los compradores desde una sola dirección IP. Haga las llamadas desde el dispositivo o el navegador del comprador. Consulte Rate limits.
El checkout muestra tarifas de punto de recogida de otros transportistas.
Active Personalización del envío en checkout en Configuración → Widget del carrito, y asegúrese de que el carrito tiene globe_PickupPointData, no solo el ID.