RutaDocs

Integraciones

Conectar WooCommerce

En unos 5 minutos los pedidos pagos de una tienda WooCommerce empiezan a llegar a Ruta como entregas. Necesitás entrar al WordPress de la tienda como administrador y al panel de Ruta como administrador de tu courier.

Nota

Probado con WordPress 7.1 y WooCommerce 11.2. Funciona con cualquier versión de WooCommerce que tenga la API REST v3 (incluida desde WooCommerce 3.5).

Antes de empezar

Requisito Dónde se ve
La tienda abre con https:// (candado) desde internet. La barra del navegador.
Los enlaces permanentes no están en «Simple». WordPress → Ajustes → Enlaces permanentes. Cualquier otra opción sirve.
Tu usuario de WordPress es administrador. WordPress → Usuarios.
Tu plan de Ruta incluye integraciones (Pro). Ruta → Mi cuenta → Tu plan.

1. Creá una clave de API en WooCommerce

  1. En el WordPress de la tienda, andá a WooCommerce → Ajustes → Avanzado → API REST.
  2. Tocá Agregar clave.
  3. Completá:
    • Descripción: Ruta
    • Usuario: tu usuario administrador.
    • Permisos: Lectura/Escritura. Ruta lee los pedidos y sólo escribe dos cosas: la nota con el link de seguimiento cuando el pedido sale y el estado Completado cuando se entrega (como el plugin de Shipday). Si preferís Lectura, también funciona: apagá Avisar a WooCommerce en los ajustes de la conexión.
  4. Tocá Generar clave de API. WooCommerce muestra la Clave del cliente (ck_…) y el Secreto del cliente (cs_…) una sola vez: dejá esa pestaña abierta.

Atención

Tratá el secreto como una contraseña: no lo mandes por mail ni por chat. Pegalo directo en Ruta.

2. Conectá la tienda en Ruta

  1. En Ruta, andá a Integraciones (en la barra de arriba del panel) y elegí WooCommerce (en Tiendas online, o buscala).
  2. Tocá Conectar en su tarjeta o en su página.
  3. Escribí la dirección de la tienda tal como la ven tus clientes, por ejemplo https://mitienda.com.uy (con o sin www, igual que en la barra del navegador).
  4. Pegá la Clave del cliente (ck_…) y el Secreto del cliente (cs_…).
  5. Tocá Conectar tienda.

Ruta guarda las claves cifradas y hace la primera consulta a la tienda. En el panel aparece la conexión Tienda mitienda.com.uy, que pasa a Conectada en cuanto la tienda responde.

Al terminar, Ruta muestra una URL de entrega y un Secreto para el webhook del paso siguiente. El secreto se muestra una sola vez: copialo antes de tocar Ya los copié.

Consejo

En Ajustes de la conexión elegís si importar sólo los pedidos ya pagos, el comercio de retiro y la zona, y si las entregas se asignan solas al entrar. Ver Ajustes de cada conexión.

3. Creá los webhooks (pedidos al instante)

Sin webhooks igual funciona: Ruta revisa la tienda cada 15 minutos. Con webhooks, cada pedido llega a Ruta segundos después de pagarse.

En el WordPress, andá a WooCommerce → Ajustes → Avanzado → Webhooks → Agregar webhook y creá dos, uno por tema:

Campo Webhook 1 Webhook 2
Nombre Ruta — pedido creado Ruta — pedido actualizado
Estado Activo Activo
Tema Pedido creado Pedido actualizado
URL de entrega La que te mostró Ruta La misma
Secreto El que te mostró Ruta El mismo
Versión de la API WP REST API Integration v3 WP REST API Integration v3

Nota

Al guardar un webhook activo, WooCommerce prueba la URL con un aviso sin firma (webhook_id=N). Ruta le responde 200 sin hacer nada más, así que el webhook queda guardado sin errores. Si ves «Error: Delivery URL returned response code: 404», la URL no es la de esta conexión.

La URL de entrega tiene esta forma:

Texto
https://<tu-courier>/api/integrations/sources/<id-de-la-conexion>/webhooks/woocommerce

Ruta acepta un aviso sólo si:

  • la firma X-WC-Webhook-Signature (HMAC-SHA256 en base64 del cuerpo, con el secreto) es correcta;
  • el origen X-WC-Webhook-Source es la misma dirección https que cargaste en el paso 2;
  • el tema es order.created u order.updated.

El aviso sólo le dice a Ruta qué pedido cambió: Ruta vuelve a consultarlo en la tienda con tu clave antes de crear la entrega. Así, un aviso falso no puede inventar una dirección.

4. Verificá que funciona

  1. Hacé un pedido de prueba en la tienda y pagalo (o marcá un pedido existente como Procesando).
  2. En Ruta, en la conexión, tocá Buscar pedidos ahora (o esperá el webhook).
  3. En Últimas búsquedas de pedidos aparece una consulta con resultado correcto, y en Entregas la entrega nueva con el nombre y la dirección de envío del pedido.

Qué datos se usan

En Ruta Sale del pedido de WooCommerce
Destinatario Envío → nombre y apellido
Dirección Envío → dirección, línea 2 y ciudad (Av. Italia 1234 apto 5, Montevideo)
Teléfono Facturación → teléfono
Instrucciones Nota del cliente
Pedido en WooCommerce Qué hace Ruta
Procesando Crea la entrega.
Procesando con pago contra entrega Crea la entrega con monto a cobrar = total del pedido, en pesos uruguayos o en dólares según la moneda del pedido (Ruta no convierte; en otra moneda no se importa).
Procesando con retiro en el local Lo ignora: no es un envío.
Pendiente de pago, En espera, Cancelado, Reembolsado, Fallido, Completado Lo ignora. Si después pasa a Procesando, se importa.

Un pedido se importa una sola vez, aunque la tienda lo avise de nuevo. Si un pedido no se puede importar (por ejemplo, no tiene dirección de envío), Ruta importa los demás igual y la ejecución lo marca con INTEGRATION_PAYLOAD_INVALID.

Si cancelás un pedido que ya es una entrega

Cuando un pedido importado pasa a Cancelado, Reembolsado o Fallido, Ruta se entera por el webhook «Pedido actualizado» o, si no hay webhooks, en la revisión siguiente (cada 15 minutos):

La entrega en Ruta Qué hace Ruta
Todavía no salió (creada, asignada o con un intento fallido) La cancela, igual que si la cancelaras en el panel.
Ya está en camino o entregada No la toca. La marca con un aviso en su detalle y en Últimas búsquedas de pedidos (INTEGRATION_ORDER_CANCELLED_LATE) para que decidas con el repartidor. Una entrega ya entregada sólo se marca si llega el webhook: la revisión periódica pregunta por las entregas abiertas.

Cada cancelación se aplica una sola vez, aunque la tienda la avise de nuevo. Si después volvés el pedido a Procesando, Ruta no reactiva la entrega: creá una nueva desde el panel.

Avisar a la tienda

Como Shipday, Ruta le cuenta a WooCommerce cómo va cada entrega:

En Ruta En WooCommerce
La entrega sale (en camino) Agrega al pedido una nota para el cliente con el link y el código de seguimiento. WooCommerce se la manda por email y la muestra en Mi cuenta.
La entrega se entrega Pasa el pedido de Procesando a Completado (WooCommerce le manda al cliente el email de pedido completado).
  • Ruta lee el pedido antes de escribir: si ya no está Procesando (lo pusiste En espera, lo cancelaste o reembolsaste), no lo toca. La nota se deja una sola vez, aunque haya reintentos.
  • Si la tienda rechaza el cambio, la conexión pasa a Requiere revisión (con una clave de sólo Lectura, INTEGRATION_CREDENTIALS_REJECTED). La entrega sigue igual y los pedidos nuevos siguen llegando.
  • Se apaga y se prende en Ajustes de la conexión → Avisar a WooCommerce. Viene prendido en las conexiones nuevas; las conexiones creadas antes del 2026-10-22 lo tienen apagado (se conectaron con clave de Lectura): cambiá la clave por una de Lectura/Escritura y prendelo.

Cambiar o revocar las claves

  • Cambiar: generá una clave nueva en WooCommerce y, en Ruta, abrí Cambiar las claves de la tienda en la conexión. Ruta te muestra un secreto de webhook nuevo: actualizalo en los dos webhooks de WooCommerce. Después borrá la clave vieja en WooCommerce.
  • Pausar: Pausar conexión en Ruta deja de traer pedidos sin tocar la tienda.
  • Revocar: borrá la clave «Ruta» en WooCommerce → Ajustes → Avanzado → API REST. Ruta deja de poder leer la tienda al instante.

Problemas frecuentes

Lo que ves Causa probable Solución
Requiere revisión con INTEGRATION_CREDENTIALS_REJECTED La clave se borró, se copió incompleta o es de Escritura sin Lectura. Generá una clave nueva de Lectura/Escritura y cargala de nuevo.
Lo mismo, justo después de que una entrega salió o se entregó La clave es de sólo Lectura y Avisar a WooCommerce está prendido. Cambiá la clave por una de Lectura/Escritura, o apagá la opción.
INTEGRATION_STORE_UPDATE_REJECTED WooCommerce no aceptó la nota o el cambio a Completado (por ejemplo, el pedido se borró). Revisá el pedido en WooCommerce y tocá Reintentar. La entrega no cambia.
Lo mismo, con una clave recién creada El hosting descarta el encabezado Authorization (pasa en algunos Apache con CGI/FastCGI). Pedile al hosting que lo deje pasar, o agregá al .htaccess de WordPress: SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1.
INTEGRATION_DESTINATION_BLOCKED La dirección no es https, tiene un puerto o apunta a una red privada. Usá la dirección pública de la tienda, la que abre con candado.
SERVICE_UNAVAILABLE repetido La tienda está caída, o un firewall (Cloudflare, Wordfence, el hosting) bloquea a Ruta. Revisá que la tienda abra y permití las consultas a /wp-json/wc/v3/ en el firewall.
Conectada, pero un pedido no llegó El pedido no está Procesando, es de retiro en el local, no tiene dirección de envío o es contra entrega en otra moneda. Revisá el estado, el método de envío y la dirección del pedido en WooCommerce.
Los webhooks figuran como Desactivados en WooCommerce WooCommerce los desactiva tras muchas entregas fallidas. Revisá la URL y el secreto, volvé a ponerlos en Activo. Mientras tanto, Ruta sigue revisando cada 15 minutos.

¿Seguís con problemas? Mandale al soporte de tu courier la hora del pedido y el código que muestra la conexión: nunca la clave ni el secreto.

Ver en Markdown