# 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.
> [!NOTE]
> 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.
> [!WARNING]
> 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é**.
> [!TIP]
> 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](integraciones.html#ajustes-de-cada-conexion).
## 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 |
> [!NOTE]
> 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:
```text
https:///api/integrations/sources//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.