RutaDocs

Recursos

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.
  • «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.

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

  • Ordenar ruta 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.

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.
  • 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. 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.

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 siguen como antes. Las entregas ya cerradas no cambian. Ver Cobros contra entrega.
  • «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

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.
  • 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.
  • 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.
  • 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.

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.
  • 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: 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.
  • 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 con su ciclo de vida; soporte; cada página en Markdown para agentes de IA (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.

Ver en Markdown