Integración de WooCommerce con Ágora: pedidos para recoger

La integración de WooCommerce con Ágora lleva al TPV los pedidos de la tienda online para recoger en el local: WooCommerce avisa a Connect Manager de cada pedido, Connect Manager lo asigna al local de recogida que eligió el cliente y lo crea en Ágora como pedido pendiente, con su fecha de recogida y, si ya está pagado, con su cobro. Si el pedido se cancela en la web, se anula también en Ágora.

Este manual es para el técnico de FOS o del distribuidor que conecta una tienda WooCommerce con los locales de un cliente.

Qué hace la integración#

• Recibe al momento los pedidos de WooCommerce por webhook y comprueba la firma de cada aviso.
• Asigna cada pedido a un local según el método de envío que eligió el cliente: cada local tiene su integración y solo se queda con los pedidos cuyo método de recogida coincide con su filtro.
• Crea el pedido en Ágora cuando pasa a Completado o En espera, como pedido pendiente con la serie y el contador configurados, el cliente, el TPV, el usuario, el centro de venta y la tarifa del local.
• Pone como fecha de recogida la que el cliente eligió en la web (campo «Fecha de Recogida» del pedido) o, si el pedido no la trae, la de creación más los días configurados.
• Registra el cobro con la forma de pago de Ágora configurada y el nombre del método de pago de la web. Los pedidos En espera entran sin cobrar.
• Anula en Ágora el pedido que se cancela en la web, si Ágora todavía lo tiene abierto.
• Copia en las notas del pedido el teléfono, el correo y la nota del cliente, y pone su nombre en los datos del cliente del pedido.
• Recupera cada hora, por la API de WooCommerce, los pedidos modificados en las últimas dos horas, por si algún aviso no llegó, y reintenta dos veces al día los que fallaron.
• Avisa por correo si un pedido llega con la fecha de recogida vacía, si pasan las horas configuradas sin pedidos, y por correo y Telegram si un pedido no se puede procesar.
• Guarda cada pedido en Pedidos → WooCommerce con su estado en la web y su estado de envío a Ágora, y permite reenviarlo.

Qué no hace#

• No envía la dirección de entrega: los pedidos son para recoger.
• No crea en Ágora los pedidos Pendiente de pago ni Procesando: entran cuando pasan a Completado o En espera.
• No envía gastos de envío, recargos ni descuentos de pedido: solo las líneas de producto con su importe.
• No busca los productos por nombre: la SKU de WooCommerce tiene que ser el Id. del producto de Ágora.
• No elige el IVA de cada producto: todas las líneas van con el impuesto de Ágora de Id. 3.
• No anula un pedido que en Ágora ya está facturado o cancelado.

Requisitos#

• WooCommerce con la API REST disponible y acceso de administrador para crear claves de API y webhooks.
• Un método de envío de recogida por local en WooCommerce, cada uno con un título distinto (por ejemplo «Recoger en tienda Centro»).
• Fecha de recogida guardada en el pedido por el plugin de la tienda, en un metadato llamado exactamente Fecha de Recogida con formato AAAA-MM-DD.
• SKU de cada producto o variación de WooCommerce igual al Id. del producto en Ágora.
• Ágora: API accesible desde Internet (puerto abierto o Zero Connect), porque Connect Manager crea los pedidos con la API de importación; una serie de pedidos que exista en el local y no sea la activa; y el impuesto de Id. 3 con el IVA que corresponde a estos productos.
• Connect Manager: local dado de alta con la URL de la API y la API key de Ágora. El alta del local y de la integración la hace FOS.

Datos que necesitamos#

Configuración paso a paso#

En WooCommerce#

1. Revisa que cada producto y cada variación tiene como SKU el Id. del producto de Ágora.
2. En WooCommerce → Ajustes → Envío, crea un método de recogida por local con un título distinto y apúntalo tal cual.
3. En WooCommerce → Ajustes → Avanzado → API REST, añade una clave con permisos de Lectura y guarda el Consumer key y el Consumer secret.
4. Los webhooks se crean después, cuando Connect Manager te dé la URL de cada local.

En Connect Manager#

1. En https://app.connectmanager.es, ve a Administración → Locales, abre el local, revisa la URL de API y la API key de Ágora y pulsa Guardar.
2. Entra en Integraciones de pedidos, pulsa Añadir y en Proveedor elige WooCommerce (AC). La otra variante de WooCommerce de la lista tiene reglas propias y no es la de este manual.
3. Credenciales:
   • URL Api: la URL de la tienda.
   • Customer key: el secreto del webhook, el mismo que pondrás en WooCommerce. Con él se comprueba la firma de cada aviso.
   • Consumer key: y Consumer secret: las claves de la API REST, para la recuperación horaria.
4. Envío y avisos:
   • Enviar pedidos a Ágora: márcala. Desmarcada, los pedidos se guardan como «Pausado» y no llegan al TPV.
   • Número de horas sin pedidos para notificar y Número de días cuando la fecha de entrega está vacía (2 si se deja vacío).
   • Email de receptor de notificaciones e Id. de chat de Telegram para recibir notificaciones (ver Telegram).
5. En Configuración de pedidos, escribe en Filtro por método de entrega el título exacto del método de recogida de este local. Las opciones Pausar el envío de pedidos después de y Pausar el envío de pedidos a Ágora las ve y las usa FOS.
6. Datos de Ágora: Serie, Cont. de pedidos (último número usado; el siguiente pedido llevará este más uno), Locales, Punto de venta (POS), Centro de venta, Método de pago, Usuario, Cliente y Tarifa. Todos son obligatorios para que el pedido se cree.
7. Pulsa Guardar y copia la URL del webhook de WooCommerce de la sección Enlaces.
8. Repite la integración en cada local de recogida, cada uno con su filtro y su serie.

En WooCommerce (webhooks)#

1. En WooCommerce → Ajustes → Avanzado → Webhooks, añade un webhook por local con Estado Activo, Tema «Pedido actualizado», URL de entrega la del local y Secreto el mismo que pusiste en Customer key. Usa la versión 3 de la API REST.
2. Añade otro igual con el tema «Pedido creado».

[!WARNING] Si el secreto del webhook no coincide con el campo Customer key, Connect Manager descarta el aviso pero contesta a WooCommerce con un 200, así que el webhook parece correcto. En el registro de entregas del webhook verás la respuesta «La firma proporcionada no es válida.».

Cómo funciona#

Cada vez que se crea o cambia un pedido, WooCommerce lo manda firmado a la URL de cada local. Connect Manager comprueba la firma, mira si el método de envío coincide con el filtro del local y guarda el pedido. Si su estado es Completado, En espera o Cancelado, le asigna el siguiente número del contador y lo importa en Ágora como pedido de la serie configurada: pendiente si está completado o en espera, cancelado si se canceló. El resultado queda en el listado de pedidos.

sequenceDiagram
    participant WEB as WooCommerce
    participant CM as Connect Manager
    participant AG as API Ágora
    WEB->>CM: Webhook firmado con el pedido
    CM->>CM: Comprueba firma y método de recogida
    CM->>CM: Guarda el pedido y asigna serie y número
    CM->>AG: Importa el pedido pendiente con fecha de recogida
    AG-->>CM: Importación correcta
    CM->>CM: Marca el pedido como Enviado
    Note over CM,AG: Si la web lo cancela se reimporta con el mismo número como cancelado

Qué se envía a Ágora#

• Cabecera: serie y número, fecha y fecha de negocio de creación en la web, fecha de recogida, estado (pendiente o cancelado), local, TPV, usuario, centro de venta y cliente de Ágora con el nombre, teléfono y correo del comprador.
• Notas: teléfono, correo y nota del cliente.
• Líneas: cada producto con su SKU como Id. de producto y de formato, el nombre de la web, la cantidad, el precio, el importe de la línea, la tarifa configurada y el impuesto de Id. 3.
• Cobro: en los pedidos completados, un pago anticipado por el total con la forma de pago configurada; en los pedidos en espera, ninguno.

Recuperación, reintentos y estados#

Cada hora, Connect Manager pide a la API de WooCommerce los pedidos modificados en las dos últimas horas y procesa los que han cambiado de estado o de fecha de recogida. Dos veces al día vuelve a intentar los pedidos que quedaron en error. En el listado, el Estado envío (Ágora) puede ser Sin enviar, En proceso, Enviado, Error o Pausado.

Cada integración solo atiende los pedidos de su método de recogida. De esos, los Pendientes de pago o Procesando se guardan y esperan; los Completados entran como pedido pendiente cobrado, los En espera como pedido pendiente sin cobrar y los Cancelados anulan el pedido en Ágora.

flowchart LR
    A[Pedido de la web] --> B{Método de recogida del local}
    B -- No --> X[Lo ignora esta integración]
    B -- Sí --> C{Estado en la web}
    C -- Pendiente o Procesando --> D[Se guarda y espera]
    C -- Completado --> E[Pedido pendiente cobrado]
    C -- En espera --> F[Pedido pendiente sin cobrar]
    C -- Cancelado --> G[Pedido cancelado en Ágora]

Comprobar que funciona#

1. En el registro del webhook de WooCommerce, comprueba que la entrega de prueba recibe un 200.
2. Haz un pedido de prueba con el método de recogida del local y la fecha de recogida, y márcalo como Completado.
3. En Pedidos → WooCommerce debe aparecer con Estado del pedido «Completado» y Estado envío «Enviado».
4. En Ágora, el pedido debe estar en la serie configurada, con la fecha de recogida, los productos correctos y el cobro.
5. Haz otro pedido y déjalo En espera: debe entrar en Ágora sin cobrar.
6. Cancela uno de los pedidos en la web: en Ágora debe quedar cancelado.
7. Haz un pedido con el método de recogida de otro local y comprueba que solo entra en ese local.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto WooCommerce con Ágora?#

Con una integración de pedidos de Connect Manager por local de recogida y un webhook de WooCommerce hacia cada una, con el mismo secreto en los dos sistemas.

¿Los pedidos de WooCommerce entran cobrados en Ágora?#

Los Completados sí, con la forma de pago de Ágora configurada. Los En espera entran sin cobrar.

¿Sirve para pedidos a domicilio?#

No. La integración no envía la dirección de entrega: está pensada para recoger en el local.

¿Cómo sabe qué producto de Ágora es cada producto de la web?#

Por la SKU: en WooCommerce tiene que ser el Id. del producto de Ágora.

¿Qué pasa si el cliente cancela el pedido en la web?#

Se reenvía a Ágora con el mismo número como cancelado, siempre que Ágora no lo haya facturado ya.

¿Por qué un pedido «Procesando» no está en el TPV?#

Porque solo se crean en Ágora los pedidos Completados o En espera; los Cancelados se anulan.

Referencias#

• Ficha de la integración: WooCommerce en el catálogo de Connect Manager.
• Avisos de las integraciones por Telegram.
• Zero Connect: publicar la API de Ágora sin abrir puertos.
• Webhooks de WooCommerce: https://woocommerce.com/document/webhooks/.
• API REST de WooCommerce: https://woocommerce.github.io/woocommerce-rest-api-docs/.