# Cambios

## 2026-10-27 — Comisión con tope, sin devoluciones de planes

- **Comisión del repartidor con tope**: el porcentaje sobre lo cobrado se calcula sobre lo cobrado **con un tope en lo que había que cobrar**, en la moneda de la entrega. Si se cobró en la otra moneda, sobre lo que había que cobrar, sin convertir. Lo cobrado guardado y la regla del vuelto no cambian, y las comisiones ya calculadas tampoco. Ver [Comisión del repartidor](cobros-y-rendicion.html#comision-del-repartidor-sobre-lo-cobrado).
- **«Cobrado de más: revisar»**: en `GET /api/collections/deliveries`, el campo nuevo **`overCollected`** (`true`, y sólo aparece en ese caso) marca un cobro por transferencia u otro medio mayor que `amountToCollect`, en la misma moneda. La descarga de Cobros suma una última columna, **Revisar**, con «Cobrado de más».
- **Planes**: Ruta no hace devoluciones de los cobros; la baja rige al final del mes pagado. Si Mercado Pago informa un cobro devuelto o con contracargo, el período pago termina en ese momento. `GET /api/account/billing/payments` ya no trae los campos de devolución y `POST /api/account/billing/payments/{id}/refund` dejó de existir. Ver [Planes](planes.html#ver-y-cambiar-tu-plan).

## 2026-10-27 — «Ordenar ruta» desde Basic

- **[Ordenar ruta](ordenar-ruta.html)** ahora está en los planes **Basic**, Pro y Business (antes, desde Pro), con las mismas funciones: el orden sugerido en el panel, **Fijar** paradas y el orden sugerido en la app del repartidor. Con plan Gratis, el panel muestra el aviso del plan Basic y se sigue ordenando a mano. Ver [Planes](planes.html).

## 2026-10-26 — Cobros en otra moneda, textos de los avisos y webhooks de «Volver a asignada»

- **Vuelto y otra moneda en Cobros**: una entrega cobrada en la otra moneda (por ejemplo, US$ 80 pagada con $ 3.300) ya no aparece como «Faltan US$ 80» y «Sobran $ 3.300». Las filas y los totales la muestran en una línea aparte: «1 cobrada en otra moneda: US$ 80,00 → $ 3.300,00, sin convertir». Los importes guardados, la rendición y la comisión no cambian. Ver [Cobros contra entrega](cobros-y-rendicion.html#rendicion-el-efectivo-que-te-entregan).
- **Vuelto mayor que el monto**: si el repartidor escribe un vuelto mayor que lo que había que cobrar, la app pregunta «¿Seguro?» antes de confirmar. La regla del vuelto es la misma.
- **«Volver a asignada»**: los webhooks `delivery.status_changed` y `delivery.assigned` de una entrega que volvió de `OUT_FOR_DELIVERY` a `ASSIGNED` suman **`data.reason`** con `"START_UNDONE"`. El campo es nuevo y sólo aparece en ese caso: así distinguís un inicio deshecho de una primera asignación. Ver [Webhooks](webhooks.html). En la app, si la oficina vuelve a «Asignada» la entrega que el repartidor tenía en camino, el teléfono deja de compartir la ubicación y le avisa «La oficina volvió a «Asignada» tu entrega».
- **Textos de los avisos**: el dueño escribe el email de cada aviso con sus palabras, con variables y vista previa; por WhatsApp sigue saliendo el texto aprobado por Meta. Ver [Textos de los avisos](avisos-al-cliente.html#textos-de-los-avisos-desde-basic).

## 2026-10-26 — Vuelto en efectivo y «Volver a asignada»

- **Vuelto en efectivo**: si el repartidor cobra en efectivo más que `amountToCollect` (en la misma moneda), `collectedAmount` es `amountToCollect` y no queda diferencia: el resto fue vuelto. Lo cobrado por transferencia u otro medio, lo cobrado de menos y lo [cobrado en otra moneda](#2026-10-25-cobro-en-otra-moneda) siguen como antes. Las entregas ya cerradas no cambian. Ver [Cobros contra entrega](cobros-y-rendicion.html#que-hace-el-repartidor).
- **«Volver a asignada»**: el repartidor (desde la app) o la oficina (desde el detalle) puede deshacer «Iniciar entrega» de una entrega iniciada por error, mientras no haya mandado foto, firma ni aviso de no entrega. La entrega pasa de `OUT_FOR_DELIVERY` a `ASSIGNED` con el mismo repartidor y `attemptNumber`, y `startedAt` vuelve a `null`. Los webhooks son los de siempre para ese cambio: `delivery.status_changed` y `delivery.assigned`. Al cliente no le llega un aviso nuevo y a tu tienda no se le avisa: si ya se le dijo «en camino», queda así.

## 2026-10-26 — Guías para tu empresa

- Siete guías nuevas, sin programar y con capturas: [Conectá tu tienda](conecta-tu-tienda.html), [Ordenar ruta](ordenar-ruta.html), [Direcciones y puntos en el mapa](direcciones-y-mapa.html), [Cobros contra entrega y rendición](cobros-y-rendicion.html), [Avisos al cliente](avisos-al-cliente.html), [Planes](planes.html) y [Preguntas del repartidor](preguntas-del-repartidor.html).
- [Errores](errores.html) suma `INVALID_CURRENCY`, que existe desde el 2026-10-25.

## 2026-10-25 — Puntos en el mapa y pedidos de Shopify

- `destinationLat`/`destinationLng` tienen que caer en Uruguay (latitud −35,2 a −30,0, longitud −58,6 a −53,0) al crear o corregir una entrega: si no, `400 VALIDATION_FAILED`. Las entregas que ya existen no cambian.
- Una entrega sin punto que llega por la API, por planilla, desde una tienda o por el formulario de un comercio puede recibir un punto **aproximado** puesto por Ruta, si la búsqueda de direcciones está activa en la cuenta y encuentra la dirección sin dudas. Nunca reemplaza un punto que mandaste; si corregís la dirección por la API, se vuelve a buscar. Ver [Direcciones y puntos en el mapa](direcciones-y-mapa.html#entregas-que-llegan-sin-punto).
- Shopify: un pedido **sin línea de envío** (por ejemplo, un borrador sin envío o sólo productos digitales) ya no crea una entrega. **Avisar a Shopify** sale apenas cambia la entrega (antes esperaba la revisión siguiente), y al volver a prenderlo no se avisa lo que pasó mientras estaba apagado. La conexión lista **Pedidos que no se importaron** con su motivo.

## 2026-10-25 — Cobro en otra moneda

- Campo nuevo **`collectedCurrency`** en la entrega (`"UYU"`, `"USD"` o `null` hasta que se cobre): la moneda de `collectedAmount`. Coincide con `currency` salvo cuando el repartidor cobró en la otra moneda (una entrega en dólares pagada en pesos, o al revés). Es opcional: un cliente que no lo lee sigue funcionando, pero `collectedAmount` puede estar en otra moneda que `amountToCollect`.
- Webhooks `delivery.delivered` y `delivery.collection_settled`: `data.currency` sigue siendo la moneda de `collectedAmount`, así que en ese caso dice la moneda en que se cobró.
- Ruta sigue sin convertir entre monedas.

## 2026-10-25 — Cobro contra entrega en pesos o dólares

- Campo opcional **`currency`** (`"UYU"` o `"USD"`) al crear y al editar una entrega, en los lotes y en el entorno de prueba. Si no lo mandás, la entrega cobra en **pesos**, como siempre: un cliente que no conoce el campo sigue funcionando igual, y sus `Idempotency-Key` también.
- Con `"USD"`, `amountToCollect`, `collectedAmount` y la rendición están en dólares. Ruta **nunca convierte** entre monedas.
- Las respuestas suman **`currency`** (`null` sin monto a cobrar) y los webhooks `delivery.delivered` y `delivery.collection_settled`, `data.currency`.
- Código nuevo **`INVALID_CURRENCY`** (`400`): otra moneda, o dólares sin monto a cobrar.
- Tiendas: un pedido de Shopify, Tiendanube o WooCommerce con cobro contra entrega en dólares ahora entra en dólares; otra moneda sigue sin importarse, con el motivo `COD_CURRENCY`.

## 2026-10-22 — Wix con la app de Ruta

- **Conectar con Wix** sin claves: el comercio instala la app de Ruta en su sitio (desde Ruta o desde el Wix App Market) y vuelve conectado; los pedidos llegan al instante. Ver [Conectar Wix](wix.html).
- **Buscar las opciones en mis pedidos**: Ruta muestra las opciones de envío de los últimos pedidos del sitio para elegir las de reparto local (`GET /api/integrations/sources/{id}/wix/shipping-options`).
- **Avisar a Wix**: cuando la entrega sale, Ruta crea un envío de «Ruta» con el código y el link de seguimiento; cuando se entrega, lo marca entregado. Encendido en las conexiones hechas con la app; con una API key empieza apagado.
- La conexión con una API key del sitio sigue como opción avanzada.

## 2026-10-22 — Shopify con la app de Ruta

- **Conectar con Shopify** sin claves: el comercio escribe la dirección de su tienda, autoriza la app de Ruta en Shopify y vuelve conectado. Ruta se suscribe sola a los avisos de pedidos. Ver [Conectar Shopify](shopify.html).
- **Avisar a Shopify** (encendido en las conexiones nuevas): cuando la entrega sale, el pedido pasa a **Preparado** con la empresa «Ruta», el código de seguimiento y el link; cuando se entrega, el envío pasa a **Entregado**. Si Shopify lo rechaza, la entrega sigue igual y la conexión muestra el nuevo código `INTEGRATION_STORE_UPDATE_REJECTED`.
- Una conexión nueva trae los pedidos creados desde **una semana antes** de conectar.
- La conexión con una app propia del comercio (claves del Dev Dashboard o token `shpat_`) sigue como opción avanzada.

## 2026-10-22 — Ajustes por conexión de tienda

- `GET /api/integrations`: cada conector lista sus `filters` (`DELIVERY_METHOD`, `PAID_ONLY`) y cada conexión su `lastImport` (`importedAt`, `deliveryId`, `reference`).
- La configuración de una conexión acepta `filters` (`deliveryMethods` en Shopify, `paidOnly` en Shopify y WooCommerce) y `assignment.autoAssign`. Ver [Integraciones](integraciones.html#ajustes-de-cada-conexion).

## 2026-10-19 — Pedidos retenidos por cupo

- Si el courier ya usó el **cupo mensual de entregas** de su plan, un pedido que llega por la API ya no se rechaza: se acepta (`201`) y queda **retenido**. La respuesta lo dice con dos campos nuevos: **`quotaHeld`** (`true`) y **`quotaHeldAt`**. La entrega sigue en `CREATED`; sale sola cuando el courier tiene cupo otra vez (nuevo mes o un plan mayor) y entonces `quotaHeld` pasa a `false`. Un cliente que no lee los campos nuevos sigue funcionando igual.
- `409 PLAN_QUOTA_EXCEEDED` ya no aparece al crear por la API. `409 PLAN_READ_ONLY` (cuenta sin pagar) sigue igual.

## 2026-10-19 — Planillas del panel

No cambia la API `/api/v1`. Si procesás automáticamente las planillas que se descargan del panel:

- **«Nota del repartidor» pasa a llamarse «Nota del cierre»** en la planilla de entregas: la nota del cierre también puede escribirla la oficina. El contenido y la posición de la columna no cambian.
- **Planilla de cobros:** ya no tiene tope de 1.000 filas por período, y suma al final las columnas `Efectivo (UYU)`, `Transferencia (UYU)` y `Otro (UYU)`. Sólo se rinde el efectivo: un cobro por transferencia u otro medio dice `No se rinde` en `Rendido UTC`. Las columnas anteriores quedan en el mismo lugar.
- **«Descargar para Excel»:** cada planilla tiene un segundo botón con la misma información para abrir con doble clic en Excel en Uruguay: separada por `;`, con coma decimal y la fecha y hora de Uruguay en una sola columna. La planilla de siempre no cambia.

## 2026-10-19 — Email de quien recibe y barrios de cada zona

- **`recipientEmail`** (opcional) al crear una entrega, en cada ítem del lote y al corregirla con `PATCH` (`""` lo borra). Las respuestas lo devuelven. Es el email que usan los avisos por email del courier.
- Las tiendas conectadas (WooCommerce, Shopify, Tiendanube, Wix, VTEX) traen el email del comprador cuando el pedido lo tiene.
- **`GET /api/v1/zones`** suma `areas`: los barrios de cada zona, para elegir bien `zoneId`.

## 2026-10-15 — Integración con Shopify

- **Shopify real**: el comercio crea una app de lectura (`read_orders`, `read_merchant_managed_fulfillment_orders`) en el Dev Dashboard, o usa una app anterior a 2026 con su token, y los pedidos pagos con envío o envío local se convierten en entregas, sin duplicados. Ver [Conectar Shopify](shopify.html).
- **Webhooks de Shopify**: «Creación de pedido», «Pago de pedido» y «Cancelación de pedido» hacen que los pedidos lleguen al instante; sin ellos, Ruta revisa la tienda cada 15 minutos.
- **Referencia del pedido**: una entrega importada de Shopify lleva el número del pedido (`#1001` → `1001`) como `externalReference`; si la API ya creó una entrega con esa referencia, Ruta la vincula en lugar de duplicarla.
- Nuevo código de error `INTEGRATION_SCOPE_MISSING`: a la app de la tienda le falta un permiso de lectura.

## 2026-10-15 — Integración con Tiendanube

- Nueva guía [Conectar Tiendanube](tiendanube.html): el comercio autoriza la app de Ruta (permiso **ver pedidos**, sin claves) y los pedidos pagos con envío a cargo de la tienda llegan como entregas, por aviso al instante y con revisión cada 15 minutos.
- Las cancelaciones de Tiendanube (pedido cancelado, pago anulado o reembolsado) cancelan la entrega si todavía no salió.
- Un pedido que tu sistema ya mandó por la API con el número de pedido como `externalReference` se une a esa entrega en lugar de duplicarla.

## 2026-10-14 — WooCommerce: qué pedidos se importan

- Se importa todo pedido **Procesando**, tenga o no fecha de pago (WooCommerce no la pone en pedidos sin productos para enviar).
- **Pago contra entrega:** la entrega lleva el total del pedido como monto a cobrar.
- **Retiro en el local** y pedidos sin pagar: se ignoran sin marcar error.
- **Cada pedido es independiente:** uno que no se puede importar ya no frena a los demás.

## 2026-10-13 — Integración con WooCommerce

- **WooCommerce real**: conectá una tienda con una clave de lectura de la API REST y los pedidos pagos se convierten en entregas, sin duplicados. Ver [Conectar WooCommerce](woocommerce.html).
- **Webhooks de WooCommerce**: con los temas «Pedido creado» y «Pedido actualizado» los pedidos llegan al instante; sin ellos, Ruta revisa la tienda cada 15 minutos.
- **Documentación**: ejemplos en curl, JavaScript, Python y PHP; [el objeto entrega](objeto-entrega.html) con su ciclo de vida; [soporte](soporte.html); cada página en Markdown para agentes de IA ([llms.txt](llms.txt)).
- **Códigos nuevos**: `INTEGRATION_CREDENTIALS_REJECTED` (la tienda rechazó las claves) e `INTEGRATION_DESTINATION_BLOCKED` (la dirección no es una tienda pública con `https`).

## 2026-10-12 — API v1+ (V41)

Todo es aditivo dentro de `/api/v1`.

- **Referencia de tu pedido**: `externalReference` en el alta, en la respuesta, en la etiqueta y en el filtro `GET /api/v1/deliveries?externalReference=`. Única por empresa y comercio (`409 EXTERNAL_REFERENCE_TAKEN`).
- **Corregir y cancelar**: `PATCH /api/v1/deliveries/{id}` y `POST /api/v1/deliveries/{id}/cancel`, con las reglas del panel.
- **Eventos con nombre**: `delivery.assigned`, `.picked_up`, `.out_for_delivery`, `.delivered`, `.failed`, `.cancelled`, `.retry_scheduled`, `.proof_added`, `.collection_settled`. Cada webhook elige sus eventos; los webhooks existentes siguen recibiendo sólo `delivery.created` y `delivery.status_changed`. Todo aviso trae `test` y, en `data`, `externalReference` y `shipperId`.
- **Evento de prueba**: «Enviar evento de prueba» en el panel (`webhook.test`).
- **Comprobante**: `GET /api/v1/deliveries/{id}/proof` con enlaces firmados de 5 minutos (permiso nuevo `proof:read`).
- **Cobro**: `collectedAmount`, `collectionMethod`, `collectedAt` y `settledAt` en cada entrega.
- **Claves por comercio**: una clave puede limitarse a un comercio; crea y ve sólo sus entregas. Los webhooks también pueden filtrarse por comercio.
- **Entorno de prueba**: claves `ruta_test_…` en un espacio aislado sin cupo, webhooks de prueba y `POST /api/v1/deliveries/{id}/simulate`.
- **Detalles**: `GET /api/v1/zones`, etiqueta PDF (`GET /api/v1/deliveries/{id}/label`), alta en lote de hasta 100 (`POST /api/v1/deliveries/batch`) y encabezados `RateLimit-*` en cada respuesta.

## 2026-10-11 — Webhooks para todas las entregas

Los avisos cubren todas las entregas de la empresa, no sólo las creadas por API; las claves de consulta ven todas las entregas de la empresa. La API está disponible en todos los planes.

## 2026-10-10 — Primera versión

`POST/GET /api/v1/deliveries`, claves con permisos, idempotencia obligatoria, webhooks firmados `delivery.created` y `delivery.status_changed`, errores RFC 9457.