Google Maps en Delivery propio: direcciones y zonas de reparto

Google Maps está detrás de todas las direcciones del delivery propio de Connect Manager, la tienda online conectada con Ágora: propone la calle mientras el cliente escribe, convierte la dirección en coordenadas para saber si cae dentro de una zona de reparto, sitúa cada local en el mapa y dibuja las zonas en el panel. Este manual es para el técnico que ubica los locales y dibuja las zonas de reparto con sus mínimos y portes: qué servicios de Google se usan, qué claves hacen falta y quién las pone, y cómo decide la tienda qué local lleva cada pedido.

Qué hace la integración#

• Propone direcciones mientras el cliente escribe (a partir de 3 caracteres), en la portada de la tienda, en el paso de pago y en «Mi cuenta». Solo propone direcciones de España (calle, portal), hasta cinco.

• Saca el punto exacto de la dirección elegida y, de la misma respuesta, la calle, el número, la ciudad, la provincia y el código postal. Esos datos viajan al pedido de Ágora cada uno en su casilla.

• Busca una dirección escrita a mano con el botón de la portada, y pone nombre a la ubicación del móvil cuando el cliente pulsa «usar mi ubicación».

• Sitúa cada local en el mapa con el botón «Buscar en Google» de su ficha; las coordenadas se pueden corregir a mano.

• Dibuja las zonas de reparto en un mapa del panel, todas a la vez para ver dónde se pisan, con vértices que se pueden arrastrar.

• Cada zona tiene pedido mínimo, coste de envío, tramos de envío por importe, envío gratis desde un importe y el producto de portes de Ágora con el que se cobra.

• Decide qué local reparte: el que tiene una zona activa que contiene la dirección; si hay varios, el abierto más cercano.

• Enseña al cliente lo que cuesta el envío antes de entrar en la carta y, en el pago, cuánto le falta para el siguiente tramo («Añade X € y el envío te cuesta Y €»).

• Ordena los locales de recogida por cercanía a la dirección del cliente.

• En el seguimiento de un pedido a domicilio, pinta un mapa con el local y la dirección de entrega unidos por una línea punteada.

• Importa de Ágora las áreas de reparto que el local ya tenga dibujadas allí, con su polígono, mínimo, porte y formato de portes.

Qué no hace#

• No calcula rutas ni tiempos por carretera: el reparto se decide con zonas dibujadas, y la distancia en línea recta solo sirve para ordenar locales.

• No sigue al repartidor: la línea del seguimiento va del local a la dirección, no es una ruta.

• No crea zonas por radio ni por código postal: se dibujan a mano o se importan de Ágora.

• No propone direcciones fuera de España ni nombres de negocios.

• No usa claves de Google del cliente: las claves son de la plataforma y las configura FOS.

• En el paso de pago la dirección de reparto se elige de la lista que propone Google: si el autocompletado no funciona, el cliente no puede completar un pedido a domicilio.

Requisitos#

• Claves de Google en el servidor de Connect Manager (las pone FOS, son comunes a todos los clientes):

  • Una clave de servidor con Geocoding API y Places API (New): sugerencias, punto exacto, búsqueda escrita, «usar mi ubicación» y «Buscar en Google» del panel.

  • Una clave de navegador con Maps JavaScript API: el mapa de áreas del panel y el mapa del seguimiento del pedido.

• El delivery propio conectado con Ágora (ver Delivery propio: conectar la tienda online con Ágora): el producto de portes se elige de los formatos de venta del ACMS.

• En Ágora, un producto de gastos de envío con su formato de venta si alguna zona cobra envío.

• Un usuario con el permiso Delivery: Configurar locales.

• Quién hace qué: FOS mantiene las claves y el proyecto de Google; el distribuidor ubica los locales, dibuja las zonas y elige el producto de portes; el cliente decide zonas, mínimos y precios de envío.

Datos que necesitamos#

Configuración paso a paso#

En Google Cloud (lo hace FOS)#

1. En el proyecto de Google de la plataforma, activa Geocoding API, Places API (New) y Maps JavaScript API.

2. Clave de servidor: limita sus APIs a Geocoding y Places (New) y guárdala en el servidor como GEOCODING_GOOGLE_KEY. Nunca se publica en ninguna página.

3. Clave de navegador: restríngela por referente HTTP a los dominios del panel y de la tienda, con Maps JavaScript API como única API, y guárdala como GOOGLE_MAPS_BROWSER_KEY. Esta sí viaja en el código de las páginas, por eso va aparte y restringida.

[!NOTE] Las sugerencias de calle se piden desde el servidor y no desde el navegador a propósito: con la clave del navegador, Places contestaba API_KEY_SERVICE_BLOCKED por sus restricciones. Si un día dejan de salir sugerencias, en el registro del servidor se distingue API_KEY_SERVICE_BLOCKED (restricciones de la clave) de SERVICE_DISABLED (API sin activar en el proyecto).

En Ágora#

1. Si alguna zona va a cobrar envío, crea el producto de gastos de envío con su formato de venta. Es lo que se elige como «Producto de los portes».

2. Si el local ya tiene las áreas de reparto dibujadas en su configuración de pedidos de Ágora, puedes traerlas en lugar de dibujarlas (paso «Importar de Ágora» más abajo).

En Connect Manager: situar el local#

1. Ve a Configuración → Locales, abre el local y entra en Ubicación y contacto.

2. Escribe la Dirección con número de portal y ciudad y pulsa Buscar en Google. Si la encuentra, rellena Latitud y Longitud.

3. Si el punto no es el bueno (la salida de la cocina está en otra calle, una plaza peatonal), corrige las coordenadas a mano.

4. Pulsa Guardar. En el listado de locales, la columna «En el mapa» queda marcada.

[!WARNING] Sin punto en el mapa el local puede repartir, pero cuando dos zonas se pisan va siempre el último en el orden: no se puede calcular qué local está más cerca.

En Connect Manager: dibujar las zonas#

1. En el mismo local, entra en Áreas de reparto. El mapa sale centrado en el local.

2. Pulsa Añadir zona y ponle nombre.

3. Con la zona en modo Dibujando, pulsa en el mapa para ir marcando el contorno y ciérralo pulsando el primer punto o con doble clic. Con la zona ya dibujada puedes arrastrar sus vértices; para editar otra, pulsa su botón «Dibujar» o pulsa sobre ella en el mapa.

4. Rellena los importes de la zona:

   • Mínimo (€): pedido mínimo de comida, sin contar descuentos.

   • Envío (€): el coste de partida.

   • Gratis desde (€): vacío es «Nunca».

   • Tramos del envío: con «+ Añadir tramo», «Desde X € el envío cuesta Y €». Por debajo del primer tramo se cobra el «Envío» de partida.

   • Producto de los portes: escribe para buscar entre los formatos de venta de Ágora.

5. Deja marcada Activa (desmarcada, la zona existe pero no cubre a nadie).

6. Pulsa Guardar áreas. Guarda todas las zonas del local de una vez; si una zona cobra envío y no tiene producto de portes, no deja guardar.

[!TIP] Si haces anillos (1 km, 2 km, 3 km con mínimo y porte crecientes), crea primero el más pequeño. Dentro de un mismo local, cuando una dirección cae en varias zonas manda la primera en el orden, y las dibujadas en el panel van por orden de creación.

En Connect Manager: traer las zonas de Ágora (opcional)#

1. Con el local emparejado con su local de Ágora (pantalla «Identidad y conexión»), ve a Configuración → Tienda pública → Conexión ACMS y pulsa Importar de Ágora.

2. Se crean las zonas con el polígono, el pedido mínimo, el coste de envío y el formato de portes de Ágora, en el orden que tienen allí.

3. Revisa cada zona en el mapa y añade tramos o envío gratis si hacen falta.

[!WARNING] Al volver a importar de Ágora, las zonas que vinieron de Ágora se sustituyen enteras por lo que haya allí, aunque las hayas retocado en el panel. Las zonas creadas en el panel no se tocan.

Cómo funciona#

De lo que escribe el cliente a la zona de reparto#

Mientras el cliente escribe su dirección, la tienda pide sugerencias a Places desde el servidor de Connect Manager (no desde el navegador), con un identificador de sesión para que Google cuente toda la búsqueda como una sola. Cuando el cliente elige una sugerencia, se pide el detalle de ese sitio: coordenadas, calle, número, ciudad, provincia y código postal. Con las coordenadas se busca qué zonas activas contienen el punto y se decide el local; la tienda responde si llega, si llega pero ahora está cerrado (y si se puede programar) o si no reparte en esa dirección, junto con el pedido mínimo y el coste de envío de la zona. El pedido se resuelve con las coordenadas y no con el texto: dos portales de la misma calle pueden caer en zonas distintas.

sequenceDiagram
    participant C as Cliente
    participant T as Tienda online
    participant G as Google Places
    participant Z as Zonas de reparto
    C->>T: Escribe la dirección
    T->>G: Autocompletado con sesión
    G-->>T: Hasta 5 direcciones de España
    C->>T: Elige una
    T->>G: Detalle del sitio
    G-->>T: Coordenadas, calle, número, ciudad y CP
    T->>Z: Qué zonas activas contienen el punto
    Z-->>T: Local, mínimo y coste de envío
    T-->>C: Llegamos, cerrado ahora o fuera de zona

Qué local reparte#

Para cada local con reparto encendido se mira si alguna de sus zonas activas contiene el punto; dentro de un local se queda con la primera que lo contiene. Si hay varios locales candidatos, se ordenan por distancia en línea recta desde la dirección y gana el más cercano que esté abierto en ese momento; si el más cercano libra ese día, reparte el siguiente. Si todos los que cubren la dirección están cerrados, la tienda enseña el horario del más cercano. Un local sin coordenadas va el último. Para la recogida no hay zonas: se enseñan todos los locales que recogen, ordenados por distancia.

flowchart TD
    P[Punto de la dirección] --> L{Algún local tiene una zona activa que lo contiene}
    L -- No --> F[Fuera de zona]
    L -- Sí --> O[Candidatos ordenados por distancia en línea recta]
    O --> A{Hay alguno abierto}
    A -- Sí --> R[Reparte el abierto más cercano con su zona]
    A -- No --> C[Cerrado, se enseña cuándo abre el más cercano]

Cuánto cuesta el envío#

El envío se calcula contra el importe de la comida sin descuentos, igual que el pedido mínimo: si ese importe llega al «Gratis desde», el envío es gratis; si no, se cobra el coste del último tramo alcanzado y, por debajo del primero, el «Envío» de partida. En el paso de pago se avisa del siguiente escalón que abarata el envío. El porte entra en Ágora como una línea más con el formato de venta elegido y el IVA de la comida.

Los mapas#

El mapa de áreas del panel y el del seguimiento del pedido se cargan en el navegador con la clave de navegador. El del seguimiento solo sale en pedidos a domicilio cuyo local tiene coordenadas y cuya dirección tiene punto, y no es una ruta: es una línea punteada del local a la dirección.

Caché y límites#

• Una dirección encontrada se recuerda 180 días (las que no se encuentran, 6 horas); una ubicación del móvil ya traducida, 30 días; una sugerencia, 5 minutos.

• Para no gastar cuota con abusos, cada conexión puede pedir 60 sugerencias por minuto y usar «mi ubicación» 20 veces cada 10 minutos.

• Las búsquedas van en español y sesgadas a España.

Comprobar que funciona#

1. «Buscar en Google» encuentra la dirección del local y la columna «En el mapa» queda marcada.

2. En «Áreas de reparto» se ve el mapa; tras dibujar y pulsar «Guardar áreas» el aviso dice «Todas tienen su zona dibujada».

3. Abre la tienda, escribe una dirección que sepas que está dentro: deben salir sugerencias y, al elegirla, el local, el mínimo y el coste de envío.

4. Prueba una dirección justo fuera de la zona: no debe ofrecer reparto. Prueba también una en la zona de solape entre dos locales.

5. En el paso de pago, añade comida hasta cruzar un tramo y comprueba que el envío cambia.

6. Haz un pedido de prueba a domicilio y revisa en Ágora la línea de portes y la dirección (calle, población y código postal en sus casillas).

7. Abre el seguimiento del pedido y comprueba que sale el mapa.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Tengo que pedirle al cliente una clave de Google Maps?#

No. Las claves son de la plataforma y las configura FOS en el servidor de Connect Manager; sirven para todas las tiendas.

¿Cómo se calcula el coste de envío del delivery propio?#

Por la zona en la que cae la dirección: el envío de partida, el tramo alcanzado según el importe de la comida sin descuentos o gratis desde el importe que pongas. No se calcula por kilómetros.

¿Qué pasa si dos zonas de locales distintos se pisan?#

Reparte el local abierto más cercano a la dirección en línea recta. Si el más cercano está cerrado, reparte el siguiente que esté abierto.

¿Puedo traer las zonas de reparto que ya tengo en Ágora?#

Sí, con «Importar de Ágora» en Tienda pública → Conexión ACMS. Trae el polígono, el pedido mínimo, el coste y el formato de portes de cada área. Si luego las retocas en el panel, una nueva importación las vuelve a dejar como están en Ágora.

¿Por qué la dirección llega a Ágora con la calle, la población y el código postal separados?#

Porque se toman de la respuesta de Google al elegir la sugerencia y cada dato va a su casilla del pedido de Ágora, en lugar de meter la línea entera en la calle.

Referencias#

• Ficha de Google Maps en el catálogo de integraciones

• Delivery propio: conectar la tienda online con Ágora

• Geocoding API (documentación de Google)

• Places API (documentación de Google)

• Maps JavaScript API (documentación de Google)

• Buenas prácticas de seguridad de las claves de Google Maps