# Documentación de integración #### Zipnova Envíos {% hint style="info" %} **Zipnova Envíos** es nuestra plataforma de gestión de envíos, con integraciones a múltiples transportes, canales de venta y marketplaces. {% endhint %} {% columns %} {% column %} **Documentación API** {% content-ref url="/spaces/3YJzYGGHMi31iTYlarRo" %} [Envíos](https://docs.zipnova.com/envios/) {% endcontent-ref %} {% endcolumn %} {% column %} **Portal de ayuda** {% embed url="" %} {% endcolumn %} {% endcolumns %} *** #### Zipnova Rutas {% hint style="info" %} **Zipnova Rutas** es nuestra plataforma de optimización y monitoreo de rutas de entrega. {% endhint %} {% columns %} {% column width="50%" %} **Documentación API** {% content-ref url="/spaces/ITffP6laRDwvNxAgsCst" %} [Rutas](https://docs.zipnova.com/rutas/) {% endcontent-ref %} {% endcolumn %} {% column width="50%" %} **Portal de ayuda** {% embed url="" %} {% endcolumn %} {% endcolumns %} *** ### Otros recursos {% columns %} {% column %} {% embed url="" fullWidth="false" %} {% endcolumn %} {% column %} {% content-ref url="/spaces/vapRjK1iJDRSdjEDOsdS" %} [Brand Kit](https://docs.zipnova.com/brand/) {% endcontent-ref %} {% endcolumn %} {% endcolumns %} *** ## :envelope\_with\_arrow: Suscripción a novedades Suscríbete a la lista para ser notificado de novedades sobre la API o aspectos importantes relacionados a las integraciones con Zipnova. {% @mailchimp/mailchimpSubscribe cta="Recibir actualizaciones por e-mail" fullWidth="false" %} # API de Rutas Introducción a la API organizacional de Zipnova Rutas ## Conociendo la API La API que se documenta en estas páginas, es la API que permite administrar diferentes aspectos de una organización. Entre lo que se permite hacer: * Crear y gestionar [envíos](/rutas/api/envios) * Crear y gestionar [workflows](/rutas/api/workflows) * Crear y gestionar [tareas](/rutas/api/tareas) * Crear y gestionar [rutas](/rutas/api/rutas) Esta API se puede usar tanto por organizaciones de tipo `carrier` y `shipper` . Las organizaciones tipo `shipper` solo pueden cotizar y crear envíos, obtener etiquetas y tracking. # Conceptos ## Organizaciones Una organización es el núcleo del sistema — representa una empresa operadora (carrier) o remitente (shipper), o ambas. Cada organización tiene un `subdomain` único que determina qué API endpoints son accesibles. A través del endpoint `GET /organizations/my` podés obtener los datos de tu propia organización: nombre, zona horaria, moneda, tipo de servicio por defecto, y configuraciones visuales. También podés consultar tus **contratos** (relaciones con otras organizaciones) y tus **lugares** (direcciones guardadas). ## Envíos Un envío representa un paquete o conjunto de paquetes que necesita ser movido de un origen a un destino. Tiene: * **Referencias**: `control_number` (generado automáticamente, 5 chars), `external_reference` (tu referencia interna) * **Partes**: `shipper` (quien envía), `carrier` (quien opera), `origin` y `destination` (direcciones) * **Contenido**: packages con peso, volumen, y `declared_value` para seguros * **Ciclo de vida** — estados progresivos: | Estado | Descripción | | -------------------- | ---------------------- | | `pending` | Creado, sin procesar | | `shipped` | En tránsito | | `picked_up` | Retirado | | `in_facility` | En depósito/hub | | `out_for_delivery` | En camino a destino | | `attempted_delivery` | Intento fallido | | `delivered` | Entregado exitosamente | | `not_delivered` | No se pudo entregar | | `cancelled` | Cancelado | Los estados de envío se pueden personalizar en cada organización. También soporta **tracking** individual y bulk, etiquetas, adjuntos, y cotizaciones previas a la creación.
## Workflows Los **Blueprints** son plantillas reutilizables que definen cómo se ejecuta un proceso logístico. Cada Blueprint tiene una serie de **Steps** (pasos) que configuran: * Qué tipo de tarea se crea en ese paso (pickup, delivery, etc.) * Qué requisitos deben cumplirse para iniciar, completar o fallar * Qué **acciones** se ejecutan automáticamente al completar/fallar el paso: crear la siguiente tarea, cancelar tareas restantes, disparar un evento, iniciar otro workflow, etc. Un **Workflow** es una instancia de un Blueprint para un caso concreto. Al crear un workflow se le pasa `data` (origen, destino, paquetes, etc.) y él se encarga de generar las tareas necesarias siguiendo los pasos del Blueprint. {% code overflow="wrap" %} ``` Blueprint (plantilla) → Steps (pasos configurados)Workflow (instancia) → Tasks (tareas ejecutadas) ``` {% endcode %} Estados del workflow: `new` → `scheduled` / `cancelled` ## Tareas Una tarea es la unidad ejecutable del sistema — lo que un repartidor o operario realmente realiza. Puede ser un retiro, una entrega, una inspección, etc. Cada tarea: * Pertenece a un **Workflow** y a un **Step** específico del blueprint * Puede estar asociada a un **Envío** (o no, si es una tarea standalone) * Tiene una **dirección** de ejecución * Puede asignarse a un **usuario** * Soporta **dependencias** entre tareas (una tarea espera a que otra termine) * Tiene **ventanas horarias** (`time_windows`) y restricciones de tiempo * Registra **firma** del receptor (`signed_by`) y **adjuntos** #### Estados de la tarea | Estado | Descripción | | ----------- | --------------------------------------------------------------- | | `pending` | Pendiente de ejecución | | `started` | En camino / iniciada | | `arrived` | En el lugar | | `complete` | Completada exitosamente | | `failed` | Falló (con razón: `no_answer`, `bad_address`, `rejected`, etc.) | | `cancelled` | Cancelada | ## Rutas Una rutaagrupa un conjunto de tareas para ser ejecutadas por un conductor con un vehículo, en una fecha determinada (`shift_date`). Permite: * **Publicar** la ruta para que el conductor la vea (`POST /routes/{id}/publish`) * **Agregar / quitar tareas** dinámicamente * Controlar **capacidad** del vehículo (peso, volumen, cantidad de paquetes) * Trackear el progreso en tiempo real #### Estados de la ruta | Estado | Descripción | | ----------- | ---------------------- | | `draft` | En planificación | | `published` | Publicada al conductor | | `blocked` | Bloqueada | | `started` | En ejecución | | `finished` | Finalizada |
# Autenticación y requests ## Autenticación Todas las llamadas requieren un token Bearer en el header `Authorization`: ``` Authorization: Bearer ``` ### Obtención del token Muy pronto podrás generar tokens desde la configuración de tu integración. ## Headers del request Además del header `authorization`, deberás enviar el header `Accept: application/json` para forzar respuestas JSON ## URL base La URL base de todos los llamados a la API organizacional tiene la siguiente estructura: {% code title="" %} ``` https://{subdomain}.routes.zipnova.app/api/v1 ``` {% endcode %} `{subdomain}` es el código de subdominio de tu organización. #### Request de ejemplo {% code title="" %} ```bash curl -L \ --url 'https://mi-organizacion.routes.zipnova.app/api/v1/organizations/my' \ --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \ --header 'Accept: application/json' ``` {% endcode %} # Respuestas de la API ## Códigos de estado Correctos * `200` OK * `201` Creado Errores en requests * `400` Request inválido * `401` No autenticado * `403` Sin permisos * `404` No encontrado * `406` No aceptable (ej: publicar una ruta sin driver o ya publicada) * `409` Rate limit excedido * `422` Error de validación (incluye `errors` con el detalle por campo) Errores en el servidor * `500` Error en el servidor ## Envelopes de respuesta Las respuestas exitosas envuelven el cuerpo bajo una clave según el recurso. {% hint style="warning" %} **Atención: la clave varía por endpoint.** {% endhint %} | Endpoint | Envelope de la respuesta | | --------------------------------- | ---------------------------------------------------------- | | `POST /shipments` | `{ "success": true, "shipment": { ... } }` | | `GET /shipments/{id}` | objeto del envío (nivel raíz) | | `POST /shipments/{id}/cancel` | `{ "success": true, "shipment": { ... } }` | | `POST /shipments/quotes` | `{ "quotes": [ ... ] }` | | `GET /shipments/{id}/tracking` | `{ "tracking": [ ... ] }` | | `POST /shipments/tracking/bulk` | `{ "tracking": [ { "shipment_id", "tracking": [...] } ] }` | | `GET /shipments/{id}/attachments` | `{ "attachments": [ ... ] }` | | `GET /tasks` | `{ "data": [ ... ], "meta": { paginación } }` | | `GET /tasks/{ulid}` | objeto de la tarea (nivel raíz) | | `POST /tasks` | `{ "success": true, "task": { ... } }` | | `POST /tasks/{ulid}/cancel` | `{ "success": true, "task": { ... } }` | | `POST /workflows` | `{ "success": true, "workflow": { "data": { ... } } }` | | `POST /workflows/{id}/cancel` | `{ "data": { "workflow": { ... } } }` | | `GET /routes` | `{ "routes": { "data": [ ... ] } }` | | `GET /routes/{id}` | objeto de la ruta (nivel raíz) | | `POST /routes` y `/publish` | `{ "success": true, "route": { ... } }` | | `GET /organizations/my` | `{ "organization": { ... } }` | | `GET /organizations/my/places` | `{ "places": [ ... ] }` | | `GET /organizations/my/contracts` | `{ "organizations": [ ... ] }` (paginado) | # Paginado Los listados (`GET /tasks`, `GET /routes`, `GET /organizations/my/contracts`) devuelven 20 ítems por página por defecto. Donde aplica, `perPage` y `page` controlan el tamaño y número de página, y la metadata de paginación se incluye en `meta`. # Organizaciones ## Endpoints ## Obtener mi organización > Retorna los datos de la organización autenticada (la que corresponde al token Bearer utilizado). ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Información de la organización autenticada"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Organization":{"description":"Organización registrada en Zipnova Rutas","properties":{"id":{"description":"Identificador público de la organización (con prefijo `org_`).","type":"string"},"name":{"description":"Nombre de la organización.","type":"string"},"subdomain":{"description":"Subdominio de la organización.","type":"string"},"custom_domain":{"description":"Dominio personalizado.","type":"string","nullable":true},"locale":{"description":"Locale por defecto.","type":"string"},"timezone":{"description":"Zona horaria de la organización.","type":"string"},"currency":{"description":"Moneda por defecto.","type":"string"},"suspended_at":{"description":"Fecha de suspensión si aplica.","type":"string","format":"date-time","nullable":true},"operational_address_id":{"description":"ID del domicilio operativo (con prefijo `ple_`).","type":"string","nullable":true}},"type":"object"}}},"paths":{"/organizations/my":{"get":{"tags":["Organizations"],"summary":"Obtener mi organización","description":"Retorna los datos de la organización autenticada (la que corresponde al token Bearer utilizado).","operationId":"getMyOrganization","responses":{"200":{"description":"Datos de la organización","content":{"application/json":{"schema":{"properties":{"organization":{"$ref":"#/components/schemas/Organization"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"}}}}}} ``` ## Listar lugares de la organización > Retorna todos los lugares operativos (depósitos, sucursales, puntos de retiro) guardados en la organización. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Información de la organización autenticada"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Place":{"description":"Lugar guardado de la organización (punto operativo)","properties":{"id":{"description":"Identificador del lugar (con prefijo `ple_`).","type":"string"},"org_id":{"description":"ID interno de la organización propietaria.","type":"integer"},"name":{"description":"Nombre del lugar.","type":"string"},"street":{"type":"string","nullable":true},"street_number":{"type":"string","nullable":true},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"phone_raw":{"description":"Teléfono sin formato E.164.","type":"string","nullable":true},"phone":{"description":"Teléfono en formato E.164.","type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"zipcode":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"state":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object"},"country":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object"}},"type":"object"}}},"paths":{"/organizations/my/places":{"get":{"tags":["Organizations"],"summary":"Listar lugares de la organización","description":"Retorna todos los lugares operativos (depósitos, sucursales, puntos de retiro) guardados en la organización.","operationId":"getMyOrganizationPlaces","responses":{"200":{"description":"Lista de lugares","content":{"application/json":{"schema":{"properties":{"places":{"type":"array","items":{"$ref":"#/components/schemas/Place"}}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"}}}}}} ``` ## Listar contratos de la organización > Retorna las organizaciones con las que existe un contrato activo.\ > Permite filtrar por tipo de licencia (\`shipper\` o \`carrier\`), ordenar y paginar resultados. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Información de la organización autenticada"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Organization":{"description":"Organización registrada en Zipnova Rutas","properties":{"id":{"description":"Identificador público de la organización (con prefijo `org_`).","type":"string"},"name":{"description":"Nombre de la organización.","type":"string"},"subdomain":{"description":"Subdominio de la organización.","type":"string"},"custom_domain":{"description":"Dominio personalizado.","type":"string","nullable":true},"locale":{"description":"Locale por defecto.","type":"string"},"timezone":{"description":"Zona horaria de la organización.","type":"string"},"currency":{"description":"Moneda por defecto.","type":"string"},"suspended_at":{"description":"Fecha de suspensión si aplica.","type":"string","format":"date-time","nullable":true},"operational_address_id":{"description":"ID del domicilio operativo (con prefijo `ple_`).","type":"string","nullable":true}},"type":"object"},"Pagination":{"description":"Metadatos de paginación","properties":{"total":{"description":"Total de registros.","type":"integer"},"per_page":{"description":"Registros por página.","type":"integer"},"current_page":{"description":"Página actual.","type":"integer"},"last_page":{"description":"Última página.","type":"integer"},"from":{"description":"Índice del primer registro de la página.","type":"integer"},"to":{"description":"Índice del último registro de la página.","type":"integer"}},"type":"object"}}},"paths":{"/organizations/my/contracts":{"get":{"tags":["Organizations"],"summary":"Listar contratos de la organización","description":"Retorna las organizaciones con las que existe un contrato activo.\nPermite filtrar por tipo de licencia (`shipper` o `carrier`), ordenar y paginar resultados.","operationId":"getMyOrganizationContracts","parameters":[{"name":"license","in":"query","description":"Tipo de licencia: `shipper` (remitentes con los que opero como carrier) o `carrier` (transportistas que me atienden como shipper). Por defecto: `shipper`.","required":false,"schema":{"type":"string","enum":["shipper","carrier"]}},{"name":"filter[global]","in":"query","description":"Búsqueda por nombre de organización o mercado.","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"Campo de ordenamiento. Prefijo `-` para descendente.","required":false,"schema":{"type":"string","enum":["organizations.name","-organizations.name","markets.name","-markets.name"]}},{"name":"perPage","in":"query","description":"Cantidad de resultados por página.","required":false,"schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Lista paginada de organizaciones con contrato","content":{"application/json":{"schema":{"properties":{"organizations":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Organization"}},"links":{"properties":{"first":{"type":"string","format":"uri","nullable":true},"last":{"type":"string","format":"uri","nullable":true},"prev":{"type":"string","format":"uri","nullable":true},"next":{"type":"string","format":"uri","nullable":true}},"type":"object"},"meta":{"$ref":"#/components/schemas/Pagination"}},"type":"object"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"}}}}}} ``` ## Modelos ## The Organization object ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Organization":{"description":"Organización registrada en Zipnova Rutas","properties":{"id":{"description":"Identificador público de la organización (con prefijo `org_`).","type":"string"},"name":{"description":"Nombre de la organización.","type":"string"},"subdomain":{"description":"Subdominio de la organización.","type":"string"},"custom_domain":{"description":"Dominio personalizado.","type":"string","nullable":true},"locale":{"description":"Locale por defecto.","type":"string"},"timezone":{"description":"Zona horaria de la organización.","type":"string"},"currency":{"description":"Moneda por defecto.","type":"string"},"suspended_at":{"description":"Fecha de suspensión si aplica.","type":"string","format":"date-time","nullable":true},"operational_address_id":{"description":"ID del domicilio operativo (con prefijo `ple_`).","type":"string","nullable":true}},"type":"object"}}}} ``` # Envíos ## Obtener cotizaciones de envío > Calcula las cotizaciones disponibles para un envío según origen, destino y paquetes. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"AddressInput":{"description":"Dirección de origen o destino. Se puede enviar de **tres formas mutuamente excluyentes**:\n\n| Modo | Qué enviar | Comportamiento |\n|------|-----------|----------------|\n| **1. Dirección existente** | solo `id` | Reutiliza una dirección ya creada, tal cual está. |\n| **2. Lugar guardado** | solo `place_id` | Copia automáticamente todos los datos desde el lugar. |\n| **3. Dirección nueva** | objeto completo | Crea una dirección nueva. |\n\n**Reglas de exclusión:**\n- `id` y `place_id` son excluyentes entre sí.\n- En el modo 3, la ubicación se indica por IDs internos (`city_id`) **o** por nombres (`city` + `state` + `country`).","oneOf":[{"$ref":"#/components/schemas/AddressByIdInput"},{"$ref":"#/components/schemas/AddressByPlaceInput"},{"$ref":"#/components/schemas/AddressNewInput"}]},"AddressByIdInput":{"title":"1. Reutilizar dirección existente (id)","description":"Reutiliza una dirección ya creada. Se usa exactamente como está; no se modifica ningún campo.","required":["id"],"properties":{"id":{"description":"ID de una dirección existente.","type":"string"}},"type":"object"},"AddressByPlaceInput":{"title":"2. Reutilizar lugar guardado (place_id)","description":"Reutiliza un lugar guardado. Todos los datos se copian automáticamente desde el lugar.","required":["place_id"],"properties":{"place_id":{"description":"ID del lugar guardado (con prefijo `ple_`). Debe existir en la lista de lugares de la organización.","type":"string"}},"type":"object"},"AddressNewInput":{"title":"3. Dirección nueva (objeto completo)","description":"Crea una dirección nueva. La ubicación se puede indicar de dos formas:\n- **Por IDs internos:** envía `city_id` (y opcionalmente `state_id` / `country_id`).\n- **Por nombres:** envía `city`, `state` y `country` (código ISO).","required":["name","street","street_number"],"properties":{"name":{"description":"Nombre del destinatario/remitente.","type":"string","maxLength":100},"street":{"description":"Nombre de la calle.","type":"string","maxLength":100},"street_number":{"description":"Altura/número.","type":"string","maxLength":10},"floor":{"description":"Piso (opcional).","type":"string","maxLength":5,"nullable":true},"apartment":{"description":"Departamento (opcional).","type":"string","maxLength":10,"nullable":true},"reference":{"description":"Referencia adicional (opcional).","type":"string","maxLength":255,"nullable":true},"city_id":{"description":"ID interno de la ciudad. Obligatorio si no se envía `city`, `state` y `country`.","type":"integer"},"city":{"description":"Nombre de la ciudad. Obligatorio si no se envía `city_id`.","type":"string"},"state_id":{"description":"ID interno de la provincia/estado (opcional).","type":"integer"},"state":{"description":"Nombre de la provincia/estado.","type":"string"},"country_id":{"description":"ID interno del país (opcional).","type":"integer"},"country":{"description":"Código ISO del país (ej: AR, MX, CL).","type":"string"},"zipcode":{"description":"Código postal (opcional).","type":"string","nullable":true},"phone":{"description":"Teléfono en formato E.164 (opcional).","type":"string","nullable":true},"email":{"description":"Email de contacto (opcional).","type":"string","format":"email","nullable":true},"document_type":{"description":"Código del tipo de documento (opcional).","type":"string","nullable":true},"document_number":{"description":"Número de documento (obligatorio si se envía `document_type`).","type":"string","nullable":true},"geo_latitude":{"description":"Latitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":90,"minimum":-90,"nullable":true},"geo_longitude":{"description":"Longitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":180,"minimum":-180,"nullable":true}},"type":"object"},"PackageInput":{"description":"Paquete a incluir en el envío o tarea. Cada medida (peso y dimensiones) se puede enviar de dos formas:\n- **Valor normalizado:** `grams` (gramos), `length`/`width`/`height` (centímetros). El sistema lo guarda tal cual.\n- **Valor con unidad:** `original_weight` + `weight_unit` (y los `original_*` + `*_unit` para dimensiones). El sistema normaliza automáticamente y conserva el valor original.\n\n**Si se envía `id`:** se reutiliza un paquete existente y los demás campos no son necesarios.\n\n**Si no se envía `id`:** `length`, `width` y `height` son obligatorios. El peso debe enviarse como `grams` **o** `original_weight` + `weight_unit`.\n\nUnidades soportadas:\n- Peso: `g`, `kg`, `mg`, `lbs`\n- Dimensiones: `cm`, `m`, `mm`, `in`\n- Temperatura: `celsius`, `fahrenheit`\n\nLa entrada es tolerante: se aceptan mayúsculas, símbolos y abreviaturas equivalentes\n(`KG`, `°C`, `F`, `inches`, `m3`, `m³`, `lt`), y el sistema las normaliza. Lo que se\n**guarda y se devuelve** es siempre el valor canónico en texto plano de la lista de arriba.","properties":{"id":{"description":"ID del paquete existente. Si se envía, los demás campos no son necesarios.","type":"integer"},"external_reference":{"description":"Referencia externa (opcional).","type":"string","maxLength":50,"nullable":true},"description":{"description":"Descripción del paquete (opcional).","type":"string","maxLength":190,"nullable":true},"label_code":{"description":"Código de etiqueta del paquete.","type":"string","maxLength":20},"length":{"description":"Largo en centímetros (normalizado).","type":"integer"},"width":{"description":"Ancho en centímetros (normalizado).","type":"integer"},"height":{"description":"Alto en centímetros (normalizado).","type":"integer"},"original_length":{"description":"Largo en la unidad original.","type":"number"},"length_unit":{"description":"Unidad del largo original.","type":"string","enum":["cm","m","mm","in"]},"original_width":{"description":"Ancho en la unidad original.","type":"number"},"width_unit":{"description":"Unidad del ancho original.","type":"string","enum":["cm","m","mm","in"]},"original_height":{"description":"Alto en la unidad original.","type":"number"},"height_unit":{"description":"Unidad del alto original.","type":"string","enum":["cm","m","mm","in"]},"grams":{"description":"Peso en gramos (normalizado). Opcional si se envía original_weight + weight_unit.","type":"integer"},"original_weight":{"description":"Peso en la unidad original. Opcional si se envía grams.","type":"number"},"weight_unit":{"description":"Unidad del peso original. Requerido si se envía original_weight.","type":"string","enum":["g","kg","mg","lbs"]},"declared_value_amount":{"description":"Valor declarado del paquete (para seguros/aduana). Por defecto 0.","type":"number","format":"float","nullable":true},"declared_value_currency":{"description":"Moneda del valor declarado (ISO 4217). Si no se especifica, se usa la moneda por defecto de la organización.","type":"string","maxLength":4,"nullable":true},"un_code":{"description":"Código UN de mercancía peligrosa.","type":"string"},"classification":{"description":"Clasificación del paquete.","type":"string"},"is_flammable":{"description":"Si el paquete es inflamable.","type":"boolean","default":false},"is_corrosive":{"description":"Si el paquete es corrosivo.","type":"boolean","default":false},"is_fragile":{"description":"Si el paquete es frágil.","type":"boolean","default":false},"temperature_min":{"description":"Temperatura mínima de transporte en grados Celsius (normalizado).","type":"number"},"temperature_max":{"description":"Temperatura máxima de transporte en grados Celsius (normalizado).","type":"number"},"original_temperature_min":{"description":"Temperatura mínima en la unidad original.","type":"number"},"temperature_min_unit":{"description":"Unidad de temperatura mínima original.","type":"string","enum":["celsius","fahrenheit"]},"original_temperature_max":{"description":"Temperatura máxima en la unidad original.","type":"number"},"temperature_max_unit":{"description":"Unidad de temperatura máxima original.","type":"string","enum":["celsius","fahrenheit"]}},"type":"object"},"Quote":{"description":"Cotización de envío","properties":{"service_type_id":{"type":"integer"},"service_type_name":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"estimated_delivery_days":{"type":"integer","nullable":true}},"type":"object"}}},"paths":{"/shipments/quotes":{"post":{"tags":["Shipments"],"summary":"Obtener cotizaciones de envío","description":"Calcula las cotizaciones disponibles para un envío según origen, destino y paquetes.","operationId":"createShipmentQuotes","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["origin","destination","packages"],"properties":{"origin":{"$ref":"#/components/schemas/AddressInput"},"destination":{"$ref":"#/components/schemas/AddressInput"},"packages":{"description":"Paquetes a cotizar.","type":"array","items":{"$ref":"#/components/schemas/PackageInput"},"minItems":1},"declared_value":{"description":"Valor declarado (opcional).","type":"number","minimum":0,"nullable":true},"shipper_id":{"description":"ID del shipper. Requerido si la org es carrier.","type":"string","nullable":true},"carrier_id":{"description":"ID del carrier. Requerido si la org es shipper.","type":"string","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Cotizaciones obtenidas","content":{"application/json":{"schema":{"properties":{"quotes":{"type":"array","items":{"$ref":"#/components/schemas/Quote"}}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"422":{"description":"Error de validación"}}}}}} ``` ## Crear envío > Crea un nuevo envío. Si la organización es carrier, \`shipper\_id\` es requerido. Si es shipper, \`carrier\_id\` es requerido. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"AddressInput":{"description":"Dirección de origen o destino. Se puede enviar de **tres formas mutuamente excluyentes**:\n\n| Modo | Qué enviar | Comportamiento |\n|------|-----------|----------------|\n| **1. Dirección existente** | solo `id` | Reutiliza una dirección ya creada, tal cual está. |\n| **2. Lugar guardado** | solo `place_id` | Copia automáticamente todos los datos desde el lugar. |\n| **3. Dirección nueva** | objeto completo | Crea una dirección nueva. |\n\n**Reglas de exclusión:**\n- `id` y `place_id` son excluyentes entre sí.\n- En el modo 3, la ubicación se indica por IDs internos (`city_id`) **o** por nombres (`city` + `state` + `country`).","oneOf":[{"$ref":"#/components/schemas/AddressByIdInput"},{"$ref":"#/components/schemas/AddressByPlaceInput"},{"$ref":"#/components/schemas/AddressNewInput"}]},"AddressByIdInput":{"title":"1. Reutilizar dirección existente (id)","description":"Reutiliza una dirección ya creada. Se usa exactamente como está; no se modifica ningún campo.","required":["id"],"properties":{"id":{"description":"ID de una dirección existente.","type":"string"}},"type":"object"},"AddressByPlaceInput":{"title":"2. Reutilizar lugar guardado (place_id)","description":"Reutiliza un lugar guardado. Todos los datos se copian automáticamente desde el lugar.","required":["place_id"],"properties":{"place_id":{"description":"ID del lugar guardado (con prefijo `ple_`). Debe existir en la lista de lugares de la organización.","type":"string"}},"type":"object"},"AddressNewInput":{"title":"3. Dirección nueva (objeto completo)","description":"Crea una dirección nueva. La ubicación se puede indicar de dos formas:\n- **Por IDs internos:** envía `city_id` (y opcionalmente `state_id` / `country_id`).\n- **Por nombres:** envía `city`, `state` y `country` (código ISO).","required":["name","street","street_number"],"properties":{"name":{"description":"Nombre del destinatario/remitente.","type":"string","maxLength":100},"street":{"description":"Nombre de la calle.","type":"string","maxLength":100},"street_number":{"description":"Altura/número.","type":"string","maxLength":10},"floor":{"description":"Piso (opcional).","type":"string","maxLength":5,"nullable":true},"apartment":{"description":"Departamento (opcional).","type":"string","maxLength":10,"nullable":true},"reference":{"description":"Referencia adicional (opcional).","type":"string","maxLength":255,"nullable":true},"city_id":{"description":"ID interno de la ciudad. Obligatorio si no se envía `city`, `state` y `country`.","type":"integer"},"city":{"description":"Nombre de la ciudad. Obligatorio si no se envía `city_id`.","type":"string"},"state_id":{"description":"ID interno de la provincia/estado (opcional).","type":"integer"},"state":{"description":"Nombre de la provincia/estado.","type":"string"},"country_id":{"description":"ID interno del país (opcional).","type":"integer"},"country":{"description":"Código ISO del país (ej: AR, MX, CL).","type":"string"},"zipcode":{"description":"Código postal (opcional).","type":"string","nullable":true},"phone":{"description":"Teléfono en formato E.164 (opcional).","type":"string","nullable":true},"email":{"description":"Email de contacto (opcional).","type":"string","format":"email","nullable":true},"document_type":{"description":"Código del tipo de documento (opcional).","type":"string","nullable":true},"document_number":{"description":"Número de documento (obligatorio si se envía `document_type`).","type":"string","nullable":true},"geo_latitude":{"description":"Latitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":90,"minimum":-90,"nullable":true},"geo_longitude":{"description":"Longitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":180,"minimum":-180,"nullable":true}},"type":"object"},"PackageInput":{"description":"Paquete a incluir en el envío o tarea. Cada medida (peso y dimensiones) se puede enviar de dos formas:\n- **Valor normalizado:** `grams` (gramos), `length`/`width`/`height` (centímetros). El sistema lo guarda tal cual.\n- **Valor con unidad:** `original_weight` + `weight_unit` (y los `original_*` + `*_unit` para dimensiones). El sistema normaliza automáticamente y conserva el valor original.\n\n**Si se envía `id`:** se reutiliza un paquete existente y los demás campos no son necesarios.\n\n**Si no se envía `id`:** `length`, `width` y `height` son obligatorios. El peso debe enviarse como `grams` **o** `original_weight` + `weight_unit`.\n\nUnidades soportadas:\n- Peso: `g`, `kg`, `mg`, `lbs`\n- Dimensiones: `cm`, `m`, `mm`, `in`\n- Temperatura: `celsius`, `fahrenheit`\n\nLa entrada es tolerante: se aceptan mayúsculas, símbolos y abreviaturas equivalentes\n(`KG`, `°C`, `F`, `inches`, `m3`, `m³`, `lt`), y el sistema las normaliza. Lo que se\n**guarda y se devuelve** es siempre el valor canónico en texto plano de la lista de arriba.","properties":{"id":{"description":"ID del paquete existente. Si se envía, los demás campos no son necesarios.","type":"integer"},"external_reference":{"description":"Referencia externa (opcional).","type":"string","maxLength":50,"nullable":true},"description":{"description":"Descripción del paquete (opcional).","type":"string","maxLength":190,"nullable":true},"label_code":{"description":"Código de etiqueta del paquete.","type":"string","maxLength":20},"length":{"description":"Largo en centímetros (normalizado).","type":"integer"},"width":{"description":"Ancho en centímetros (normalizado).","type":"integer"},"height":{"description":"Alto en centímetros (normalizado).","type":"integer"},"original_length":{"description":"Largo en la unidad original.","type":"number"},"length_unit":{"description":"Unidad del largo original.","type":"string","enum":["cm","m","mm","in"]},"original_width":{"description":"Ancho en la unidad original.","type":"number"},"width_unit":{"description":"Unidad del ancho original.","type":"string","enum":["cm","m","mm","in"]},"original_height":{"description":"Alto en la unidad original.","type":"number"},"height_unit":{"description":"Unidad del alto original.","type":"string","enum":["cm","m","mm","in"]},"grams":{"description":"Peso en gramos (normalizado). Opcional si se envía original_weight + weight_unit.","type":"integer"},"original_weight":{"description":"Peso en la unidad original. Opcional si se envía grams.","type":"number"},"weight_unit":{"description":"Unidad del peso original. Requerido si se envía original_weight.","type":"string","enum":["g","kg","mg","lbs"]},"declared_value_amount":{"description":"Valor declarado del paquete (para seguros/aduana). Por defecto 0.","type":"number","format":"float","nullable":true},"declared_value_currency":{"description":"Moneda del valor declarado (ISO 4217). Si no se especifica, se usa la moneda por defecto de la organización.","type":"string","maxLength":4,"nullable":true},"un_code":{"description":"Código UN de mercancía peligrosa.","type":"string"},"classification":{"description":"Clasificación del paquete.","type":"string"},"is_flammable":{"description":"Si el paquete es inflamable.","type":"boolean","default":false},"is_corrosive":{"description":"Si el paquete es corrosivo.","type":"boolean","default":false},"is_fragile":{"description":"Si el paquete es frágil.","type":"boolean","default":false},"temperature_min":{"description":"Temperatura mínima de transporte en grados Celsius (normalizado).","type":"number"},"temperature_max":{"description":"Temperatura máxima de transporte en grados Celsius (normalizado).","type":"number"},"original_temperature_min":{"description":"Temperatura mínima en la unidad original.","type":"number"},"temperature_min_unit":{"description":"Unidad de temperatura mínima original.","type":"string","enum":["celsius","fahrenheit"]},"original_temperature_max":{"description":"Temperatura máxima en la unidad original.","type":"number"},"temperature_max_unit":{"description":"Unidad de temperatura máxima original.","type":"string","enum":["celsius","fahrenheit"]}},"type":"object"},"Shipment":{"description":"Envío completo con todos sus datos","properties":{"id":{"description":"ID interno del envío.","type":"integer","format":"int64"},"ulid":{"description":"Identificador secundario del envío.","type":"string"},"external_reference":{"description":"Referencia externa del envío.","type":"string","nullable":true},"control_number":{"description":"Número de control del envío.","type":"string","nullable":true},"serviceType":{"description":"Tipo de servicio asociado al envío","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"shipper":{"description":"Organización dadora de carga","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"carrier":{"description":"Organización transportista","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"status":{"description":"Estado actual del envío","properties":{"code":{"type":"string"},"name":{"type":"string"},"color":{"description":"Color hexadecimal del estado.","type":"string","nullable":true},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object"},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"properties":{"total_packages":{"type":"integer"},"total_grams":{"description":"Peso total en gramos.","type":"number"},"total_cm3":{"description":"Volumen total en centímetros cúbicos.","type":"number"}},"type":"object"},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"related_shipment_id":{"description":"ID del envío relacionado (ej. retorno o reenvío).","type":"integer","nullable":true},"related_type":{"description":"Tipo de relación con el envío asociado.","type":"string","nullable":true},"finished_at":{"description":"Fecha en que el envío fue finalizado.","type":"string","format":"date-time","nullable":true},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"label_printed_at":{"type":"string","format":"date-time","nullable":true},"shipped_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/shipments":{"post":{"tags":["Shipments"],"summary":"Crear envío","description":"Crea un nuevo envío. Si la organización es carrier, `shipper_id` es requerido. Si es shipper, `carrier_id` es requerido.","operationId":"createShipment","requestBody":{"description":"Datos del envío a crear","required":true,"content":{"application/json":{"schema":{"required":["origin","destination","packages"],"properties":{"origin":{"$ref":"#/components/schemas/AddressInput"},"destination":{"$ref":"#/components/schemas/AddressInput"},"packages":{"description":"Paquetes del envío (mínimo 1).","type":"array","items":{"$ref":"#/components/schemas/PackageInput"},"minItems":1},"external_reference":{"description":"Referencia externa del envío.","type":"string","maxLength":50,"nullable":true},"declared_value":{"description":"Valor declarado del envío.","type":"number","minimum":0,"nullable":true},"declared_value_currency":{"description":"Moneda del valor declarado (debe ser válida para la organización).","type":"string","nullable":true},"requires_pickup":{"description":"Si el envío requiere pickup previo.","type":"boolean","default":false},"is_public":{"description":"Si el tracking del envío es público.","type":"boolean","default":false},"shipper_id":{"description":"ID del shipper. Requerido si la org es carrier.","type":"string"},"carrier_id":{"description":"ID del carrier. Requerido si la org es shipper.","type":"string"},"service_type_id":{"description":"ID del tipo de servicio (opcional).","type":"integer","nullable":true},"service_type_code":{"description":"Código del tipo de servicio (alternativa a service_type_id).","type":"string","nullable":true},"merchant":{"description":"Información del comercio (opcional)","properties":{"name":{"type":"string"},"code":{"type":"string"}},"type":"object","nullable":true},"promised_delivery_at":{"description":"Fecha prometida de entrega.","type":"string","format":"date-time","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Envío creado","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"shipment":{"$ref":"#/components/schemas/Shipment"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"422":{"description":"Error de validación"}}}}}} ``` ## Obtener envío > Obtiene los detalles completos de un envío. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Shipment":{"description":"Envío completo con todos sus datos","properties":{"id":{"description":"ID interno del envío.","type":"integer","format":"int64"},"ulid":{"description":"Identificador secundario del envío.","type":"string"},"external_reference":{"description":"Referencia externa del envío.","type":"string","nullable":true},"control_number":{"description":"Número de control del envío.","type":"string","nullable":true},"serviceType":{"description":"Tipo de servicio asociado al envío","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"shipper":{"description":"Organización dadora de carga","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"carrier":{"description":"Organización transportista","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"status":{"description":"Estado actual del envío","properties":{"code":{"type":"string"},"name":{"type":"string"},"color":{"description":"Color hexadecimal del estado.","type":"string","nullable":true},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object"},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"properties":{"total_packages":{"type":"integer"},"total_grams":{"description":"Peso total en gramos.","type":"number"},"total_cm3":{"description":"Volumen total en centímetros cúbicos.","type":"number"}},"type":"object"},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"related_shipment_id":{"description":"ID del envío relacionado (ej. retorno o reenvío).","type":"integer","nullable":true},"related_type":{"description":"Tipo de relación con el envío asociado.","type":"string","nullable":true},"finished_at":{"description":"Fecha en que el envío fue finalizado.","type":"string","format":"date-time","nullable":true},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"label_printed_at":{"type":"string","format":"date-time","nullable":true},"shipped_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/shipments/{shipment}":{"get":{"tags":["Shipments"],"summary":"Obtener envío","description":"Obtiene los detalles completos de un envío.","operationId":"getShipment","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Envío obtenido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Envío no encontrado"}}}}}} ``` ## Seguimiento de envío > Retorna el historial de estados del envío ordenado cronológicamente. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"ShipmentTrackingEvent":{"description":"Evento del historial de seguimiento de un envío","properties":{"status":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object"},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"occurred_at":{"type":"string","format":"date-time"},"comments":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"}}},"paths":{"/shipments/{shipment}/tracking":{"get":{"tags":["Shipments"],"summary":"Seguimiento de envío","description":"Retorna el historial de estados del envío ordenado cronológicamente.","operationId":"getShipmentTracking","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Historial de seguimiento","content":{"application/json":{"schema":{"properties":{"tracking":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentTrackingEvent"}}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Envío no encontrado"}}}}}} ``` ## Seguimiento masivo de envíos > Retorna el historial de seguimiento para múltiples envíos en una sola llamada. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"ShipmentTrackingEvent":{"description":"Evento del historial de seguimiento de un envío","properties":{"status":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object"},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"occurred_at":{"type":"string","format":"date-time"},"comments":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"}}},"paths":{"/shipments/tracking/bulk":{"post":{"tags":["Shipments"],"summary":"Seguimiento masivo de envíos","description":"Retorna el historial de seguimiento para múltiples envíos en una sola llamada.","operationId":"getBulkTracking","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["shipments"],"properties":{"shipments":{"description":"IDs de los envíos a consultar.","type":"array","items":{"type":"integer"}}},"type":"object"}}}},"responses":{"200":{"description":"Seguimiento masivo","content":{"application/json":{"schema":{"properties":{"tracking":{"type":"array","items":{"properties":{"shipment_id":{"type":"integer"},"tracking":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentTrackingEvent"}}},"type":"object"}}},"type":"object"}}}},"401":{"description":"No autenticado"},"422":{"description":"Error de validación"}}}}}} ``` ## Obtener etiquetas del envío > Genera y retorna las etiquetas del envío en formato PDF, PNG o ZPL. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}}},"paths":{"/shipments/{shipment}/documentation/labels":{"get":{"tags":["Shipments"],"summary":"Obtener etiquetas del envío","description":"Genera y retorna las etiquetas del envío en formato PDF, PNG o ZPL.","operationId":"getShipmentLabels","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}},{"name":"format","in":"query","description":"Formato de salida de la etiqueta","required":true,"schema":{"type":"string","enum":["pdf","png","zpl"]}},{"name":"output","in":"query","description":"Modo de salida: `base64` retorna el archivo codificado en base64 (por defecto), `stream` lo retorna como stream, `download` como descarga.","required":false,"schema":{"type":"string","default":"base64","enum":["base64","stream","download"]}}],"responses":{"200":{"description":"Etiquetas generadas. Para output=base64 (por defecto), retorna JSON con las etiquetas codificadas. Para output=stream o download, retorna el archivo binario directamente (no JSON).","content":{"application/json":{"schema":{"description":"Respuesta JSON cuando output=base64 (por defecto).","properties":{"data":{"properties":{"file":{"description":"Etiqueta en base64 (para format=pdf o zpl).","type":"string","format":"byte","nullable":true},"files":{"description":"Etiquetas en base64 (para format=png, una por página).","type":"array","items":{"type":"string","format":"byte"},"nullable":true}},"type":"object"}},"type":"object"}},"application/octet-stream":{"schema":{"description":"Archivo binario cuando output=stream o download.","type":"string","format":"binary"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Envío no encontrado"},"422":{"description":"Formato inválido"}}}}}} ``` ## Listar adjuntos del envío > Retorna la lista de archivos adjuntos de todas las tareas del envío. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"AttachmentSummary":{"description":"Resumen de un adjunto sin contenido","properties":{"id":{"type":"string","format":"uuid"},"group":{"type":"string"},"name":{"type":"string"},"mime_type":{"type":"string"},"size":{"description":"Tamaño en bytes.","type":"integer"},"created_at":{"type":"string","format":"date-time"}},"type":"object"}}},"paths":{"/shipments/{shipment}/attachments":{"get":{"tags":["Shipments"],"summary":"Listar adjuntos del envío","description":"Retorna la lista de archivos adjuntos de todas las tareas del envío.","operationId":"getShipmentAttachments","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Lista de adjuntos","content":{"application/json":{"schema":{"properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentSummary"}}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Envío no encontrado"}}}}}} ``` ## Obtener adjunto del envío > Retorna el contenido de un adjunto específico del envío, codificado en base64. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Attachment":{"description":"Adjunto con contenido en base64","properties":{"id":{"type":"string","format":"uuid"},"group":{"type":"string"},"name":{"type":"string"},"mime_type":{"type":"string"},"size":{"description":"Tamaño en bytes.","type":"integer"},"created_at":{"type":"string","format":"date-time"},"content":{"description":"Contenido del archivo codificado en base64.","type":"string","format":"byte"}},"type":"object"}}},"paths":{"/shipments/{shipment}/attachments/{attachment}":{"get":{"tags":["Shipments"],"summary":"Obtener adjunto del envío","description":"Retorna el contenido de un adjunto específico del envío, codificado en base64.","operationId":"getShipmentAttachment","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}},{"name":"attachment","in":"path","description":"UUID del adjunto","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Adjunto obtenido con contenido en base64","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attachment"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Adjunto no encontrado"}}}}}} ``` ## Cancelar envío > Cancela un envío. Cancela automáticamente todas las tareas y workflows pendientes asociados. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Shipment":{"description":"Envío completo con todos sus datos","properties":{"id":{"description":"ID interno del envío.","type":"integer","format":"int64"},"ulid":{"description":"Identificador secundario del envío.","type":"string"},"external_reference":{"description":"Referencia externa del envío.","type":"string","nullable":true},"control_number":{"description":"Número de control del envío.","type":"string","nullable":true},"serviceType":{"description":"Tipo de servicio asociado al envío","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"shipper":{"description":"Organización dadora de carga","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"carrier":{"description":"Organización transportista","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"status":{"description":"Estado actual del envío","properties":{"code":{"type":"string"},"name":{"type":"string"},"color":{"description":"Color hexadecimal del estado.","type":"string","nullable":true},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object"},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"properties":{"total_packages":{"type":"integer"},"total_grams":{"description":"Peso total en gramos.","type":"number"},"total_cm3":{"description":"Volumen total en centímetros cúbicos.","type":"number"}},"type":"object"},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"related_shipment_id":{"description":"ID del envío relacionado (ej. retorno o reenvío).","type":"integer","nullable":true},"related_type":{"description":"Tipo de relación con el envío asociado.","type":"string","nullable":true},"finished_at":{"description":"Fecha en que el envío fue finalizado.","type":"string","format":"date-time","nullable":true},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"label_printed_at":{"type":"string","format":"date-time","nullable":true},"shipped_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/shipments/{shipment}/cancel":{"post":{"tags":["Shipments"],"summary":"Cancelar envío","description":"Cancela un envío. Cancela automáticamente todas las tareas y workflows pendientes asociados.","operationId":"cancelShipment","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Envío cancelado","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"shipment":{"$ref":"#/components/schemas/Shipment"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Envío no encontrado"},"422":{"description":"El envío no puede cancelarse en su estado actual"}}}}}} ``` ## The Shipment object ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Shipment":{"description":"Envío completo con todos sus datos","properties":{"id":{"description":"ID interno del envío.","type":"integer","format":"int64"},"ulid":{"description":"Identificador secundario del envío.","type":"string"},"external_reference":{"description":"Referencia externa del envío.","type":"string","nullable":true},"control_number":{"description":"Número de control del envío.","type":"string","nullable":true},"serviceType":{"description":"Tipo de servicio asociado al envío","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"shipper":{"description":"Organización dadora de carga","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"carrier":{"description":"Organización transportista","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"status":{"description":"Estado actual del envío","properties":{"code":{"type":"string"},"name":{"type":"string"},"color":{"description":"Color hexadecimal del estado.","type":"string","nullable":true},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object"},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"properties":{"total_packages":{"type":"integer"},"total_grams":{"description":"Peso total en gramos.","type":"number"},"total_cm3":{"description":"Volumen total en centímetros cúbicos.","type":"number"}},"type":"object"},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"related_shipment_id":{"description":"ID del envío relacionado (ej. retorno o reenvío).","type":"integer","nullable":true},"related_type":{"description":"Tipo de relación con el envío asociado.","type":"string","nullable":true},"finished_at":{"description":"Fecha en que el envío fue finalizado.","type":"string","format":"date-time","nullable":true},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"label_printed_at":{"type":"string","format":"date-time","nullable":true},"shipped_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"}}}} ``` ## The Package object ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"}}}} ``` # Workflows ## Endpoints ## Crear workflow > Crea un nuevo workflow. Requiere \`blueprint\_code\` o \`blueprint\_id\`.\ > \ > Si se envía \`shipment\_id\`, el workflow se crea a partir de un envío existente y origin/destination/packages se toman del envío (salvo que el blueprint requiera \`crossdock\`). ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"AddressInput":{"description":"Dirección de origen o destino. Se puede enviar de **tres formas mutuamente excluyentes**:\n\n| Modo | Qué enviar | Comportamiento |\n|------|-----------|----------------|\n| **1. Dirección existente** | solo `id` | Reutiliza una dirección ya creada, tal cual está. |\n| **2. Lugar guardado** | solo `place_id` | Copia automáticamente todos los datos desde el lugar. |\n| **3. Dirección nueva** | objeto completo | Crea una dirección nueva. |\n\n**Reglas de exclusión:**\n- `id` y `place_id` son excluyentes entre sí.\n- En el modo 3, la ubicación se indica por IDs internos (`city_id`) **o** por nombres (`city` + `state` + `country`).","oneOf":[{"$ref":"#/components/schemas/AddressByIdInput"},{"$ref":"#/components/schemas/AddressByPlaceInput"},{"$ref":"#/components/schemas/AddressNewInput"}]},"AddressByIdInput":{"title":"1. Reutilizar dirección existente (id)","description":"Reutiliza una dirección ya creada. Se usa exactamente como está; no se modifica ningún campo.","required":["id"],"properties":{"id":{"description":"ID de una dirección existente.","type":"string"}},"type":"object"},"AddressByPlaceInput":{"title":"2. Reutilizar lugar guardado (place_id)","description":"Reutiliza un lugar guardado. Todos los datos se copian automáticamente desde el lugar.","required":["place_id"],"properties":{"place_id":{"description":"ID del lugar guardado (con prefijo `ple_`). Debe existir en la lista de lugares de la organización.","type":"string"}},"type":"object"},"AddressNewInput":{"title":"3. Dirección nueva (objeto completo)","description":"Crea una dirección nueva. La ubicación se puede indicar de dos formas:\n- **Por IDs internos:** envía `city_id` (y opcionalmente `state_id` / `country_id`).\n- **Por nombres:** envía `city`, `state` y `country` (código ISO).","required":["name","street","street_number"],"properties":{"name":{"description":"Nombre del destinatario/remitente.","type":"string","maxLength":100},"street":{"description":"Nombre de la calle.","type":"string","maxLength":100},"street_number":{"description":"Altura/número.","type":"string","maxLength":10},"floor":{"description":"Piso (opcional).","type":"string","maxLength":5,"nullable":true},"apartment":{"description":"Departamento (opcional).","type":"string","maxLength":10,"nullable":true},"reference":{"description":"Referencia adicional (opcional).","type":"string","maxLength":255,"nullable":true},"city_id":{"description":"ID interno de la ciudad. Obligatorio si no se envía `city`, `state` y `country`.","type":"integer"},"city":{"description":"Nombre de la ciudad. Obligatorio si no se envía `city_id`.","type":"string"},"state_id":{"description":"ID interno de la provincia/estado (opcional).","type":"integer"},"state":{"description":"Nombre de la provincia/estado.","type":"string"},"country_id":{"description":"ID interno del país (opcional).","type":"integer"},"country":{"description":"Código ISO del país (ej: AR, MX, CL).","type":"string"},"zipcode":{"description":"Código postal (opcional).","type":"string","nullable":true},"phone":{"description":"Teléfono en formato E.164 (opcional).","type":"string","nullable":true},"email":{"description":"Email de contacto (opcional).","type":"string","format":"email","nullable":true},"document_type":{"description":"Código del tipo de documento (opcional).","type":"string","nullable":true},"document_number":{"description":"Número de documento (obligatorio si se envía `document_type`).","type":"string","nullable":true},"geo_latitude":{"description":"Latitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":90,"minimum":-90,"nullable":true},"geo_longitude":{"description":"Longitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":180,"minimum":-180,"nullable":true}},"type":"object"},"WorkflowSetting":{"description":"Configuración de un paso del workflow (step settings)","properties":{"step_code":{"description":"Código del step del blueprint.","type":"string"},"requirements_start":{"description":"Requisitos personalizados para iniciar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true},"requirements_complete":{"description":"Requisitos personalizados para completar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true},"requirements_fail":{"description":"Requisitos personalizados para fallar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"PackageInput":{"description":"Paquete a incluir en el envío o tarea. Cada medida (peso y dimensiones) se puede enviar de dos formas:\n- **Valor normalizado:** `grams` (gramos), `length`/`width`/`height` (centímetros). El sistema lo guarda tal cual.\n- **Valor con unidad:** `original_weight` + `weight_unit` (y los `original_*` + `*_unit` para dimensiones). El sistema normaliza automáticamente y conserva el valor original.\n\n**Si se envía `id`:** se reutiliza un paquete existente y los demás campos no son necesarios.\n\n**Si no se envía `id`:** `length`, `width` y `height` son obligatorios. El peso debe enviarse como `grams` **o** `original_weight` + `weight_unit`.\n\nUnidades soportadas:\n- Peso: `g`, `kg`, `mg`, `lbs`\n- Dimensiones: `cm`, `m`, `mm`, `in`\n- Temperatura: `celsius`, `fahrenheit`\n\nLa entrada es tolerante: se aceptan mayúsculas, símbolos y abreviaturas equivalentes\n(`KG`, `°C`, `F`, `inches`, `m3`, `m³`, `lt`), y el sistema las normaliza. Lo que se\n**guarda y se devuelve** es siempre el valor canónico en texto plano de la lista de arriba.","properties":{"id":{"description":"ID del paquete existente. Si se envía, los demás campos no son necesarios.","type":"integer"},"external_reference":{"description":"Referencia externa (opcional).","type":"string","maxLength":50,"nullable":true},"description":{"description":"Descripción del paquete (opcional).","type":"string","maxLength":190,"nullable":true},"label_code":{"description":"Código de etiqueta del paquete.","type":"string","maxLength":20},"length":{"description":"Largo en centímetros (normalizado).","type":"integer"},"width":{"description":"Ancho en centímetros (normalizado).","type":"integer"},"height":{"description":"Alto en centímetros (normalizado).","type":"integer"},"original_length":{"description":"Largo en la unidad original.","type":"number"},"length_unit":{"description":"Unidad del largo original.","type":"string","enum":["cm","m","mm","in"]},"original_width":{"description":"Ancho en la unidad original.","type":"number"},"width_unit":{"description":"Unidad del ancho original.","type":"string","enum":["cm","m","mm","in"]},"original_height":{"description":"Alto en la unidad original.","type":"number"},"height_unit":{"description":"Unidad del alto original.","type":"string","enum":["cm","m","mm","in"]},"grams":{"description":"Peso en gramos (normalizado). Opcional si se envía original_weight + weight_unit.","type":"integer"},"original_weight":{"description":"Peso en la unidad original. Opcional si se envía grams.","type":"number"},"weight_unit":{"description":"Unidad del peso original. Requerido si se envía original_weight.","type":"string","enum":["g","kg","mg","lbs"]},"declared_value_amount":{"description":"Valor declarado del paquete (para seguros/aduana). Por defecto 0.","type":"number","format":"float","nullable":true},"declared_value_currency":{"description":"Moneda del valor declarado (ISO 4217). Si no se especifica, se usa la moneda por defecto de la organización.","type":"string","maxLength":4,"nullable":true},"un_code":{"description":"Código UN de mercancía peligrosa.","type":"string"},"classification":{"description":"Clasificación del paquete.","type":"string"},"is_flammable":{"description":"Si el paquete es inflamable.","type":"boolean","default":false},"is_corrosive":{"description":"Si el paquete es corrosivo.","type":"boolean","default":false},"is_fragile":{"description":"Si el paquete es frágil.","type":"boolean","default":false},"temperature_min":{"description":"Temperatura mínima de transporte en grados Celsius (normalizado).","type":"number"},"temperature_max":{"description":"Temperatura máxima de transporte en grados Celsius (normalizado).","type":"number"},"original_temperature_min":{"description":"Temperatura mínima en la unidad original.","type":"number"},"temperature_min_unit":{"description":"Unidad de temperatura mínima original.","type":"string","enum":["celsius","fahrenheit"]},"original_temperature_max":{"description":"Temperatura máxima en la unidad original.","type":"number"},"temperature_max_unit":{"description":"Unidad de temperatura máxima original.","type":"string","enum":["celsius","fahrenheit"]}},"type":"object"},"Workflow":{"description":"Workflow que agrupa las tareas de un envío o proceso logístico","properties":{"id":{"description":"Identificador del workflow.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"current_status":{"description":"Estado actual del workflow.","type":"string"},"blueprint":{"description":"Blueprint que define la estructura del workflow. Puede ser null si el blueprint fue eliminado.","properties":{"id":{"type":"integer"},"code":{"type":"string"},"steps":{"description":"Pasos del blueprint. Solo presente en respuestas de resumen (WorkflowSummaryResource).","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"data":{"description":"Datos adicionales asociados al workflow (estructura variable según el blueprint).","type":"object","nullable":true},"tasks":{"description":"Tareas del workflow. Con include_tasks=1 retorna objetos `Task` completos; sin ese parámetro retorna resúmenes `TaskSummary` (subset reducido).","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Task"}},{"type":"array","items":{"$ref":"#/components/schemas/TaskSummary"}}]}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"},"TaskSummary":{"description":"Resumen reducido de una tarea, retornado en contextos de workflow sin include_tasks=1.","properties":{"id":{"description":"ULID de la tarea.","type":"string"},"internal_id":{"description":"ID numérico interno de la tarea.","type":"integer"},"carrier":{"properties":{"id":{"type":"integer"}},"type":"object"},"shipment":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true}},"type":"object","nullable":true},"step":{"properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de tipo pickup.","type":"boolean"},"status":{"properties":{"id":{"type":"integer"},"code":{"type":"string"}},"type":"object"}},"type":"object"}}},"paths":{"/workflows":{"post":{"tags":["Workflows"],"summary":"Crear workflow","description":"Crea un nuevo workflow. Requiere `blueprint_code` o `blueprint_id`.\n\nSi se envía `shipment_id`, el workflow se crea a partir de un envío existente y origin/destination/packages se toman del envío (salvo que el blueprint requiera `crossdock`).","operationId":"createWorkflow","requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"blueprint_code":{"description":"Código del blueprint. Requerido si no se envía `blueprint_id`.","type":"string"},"blueprint_id":{"description":"ID del blueprint. Requerido si no se envía `blueprint_code`.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"shipment_id":{"description":"ID del envío existente. Si se envía, origin/destination/packages se toman del envío.","type":"integer","nullable":true},"crossdock":{"$ref":"#/components/schemas/AddressInput"},"settings":{"description":"Configuraciones personalizadas por step del blueprint.","type":"array","items":{"$ref":"#/components/schemas/WorkflowSetting"}},"packages":{"description":"Paquetes (requerido si el blueprint lo indica y no se envía shipment_id).","type":"array","items":{"$ref":"#/components/schemas/PackageInput"}}},"type":"object"}}}},"responses":{"201":{"description":"Workflow creado","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"workflow":{"$ref":"#/components/schemas/Workflow"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"422":{"description":"Error de validación"}}}}}} ``` ## Obtener workflow > Obtiene los detalles de un workflow. Por defecto retorna el resumen; para incluir las tareas enviá \`include\_tasks=1\`. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Workflow":{"description":"Workflow que agrupa las tareas de un envío o proceso logístico","properties":{"id":{"description":"Identificador del workflow.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"current_status":{"description":"Estado actual del workflow.","type":"string"},"blueprint":{"description":"Blueprint que define la estructura del workflow. Puede ser null si el blueprint fue eliminado.","properties":{"id":{"type":"integer"},"code":{"type":"string"},"steps":{"description":"Pasos del blueprint. Solo presente en respuestas de resumen (WorkflowSummaryResource).","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"data":{"description":"Datos adicionales asociados al workflow (estructura variable según el blueprint).","type":"object","nullable":true},"tasks":{"description":"Tareas del workflow. Con include_tasks=1 retorna objetos `Task` completos; sin ese parámetro retorna resúmenes `TaskSummary` (subset reducido).","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Task"}},{"type":"array","items":{"$ref":"#/components/schemas/TaskSummary"}}]}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"},"TaskSummary":{"description":"Resumen reducido de una tarea, retornado en contextos de workflow sin include_tasks=1.","properties":{"id":{"description":"ULID de la tarea.","type":"string"},"internal_id":{"description":"ID numérico interno de la tarea.","type":"integer"},"carrier":{"properties":{"id":{"type":"integer"}},"type":"object"},"shipment":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true}},"type":"object","nullable":true},"step":{"properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de tipo pickup.","type":"boolean"},"status":{"properties":{"id":{"type":"integer"},"code":{"type":"string"}},"type":"object"}},"type":"object"}}},"paths":{"/workflows/{workflow}":{"get":{"tags":["Workflows"],"summary":"Obtener workflow","description":"Obtiene los detalles de un workflow. Por defecto retorna el resumen; para incluir las tareas enviá `include_tasks=1`.","operationId":"getWorkflow","parameters":[{"name":"workflow","in":"path","description":"ID del workflow","required":true,"schema":{"type":"integer"}},{"name":"include_tasks","in":"query","description":"Si se envía con valor `1`, incluye las tareas del workflow en la respuesta.","required":false,"schema":{"type":"integer","enum":[0,1]}}],"responses":{"200":{"description":"Workflow obtenido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Workflow no encontrado"}}}}}} ``` ## Actualizar workflow > Actualiza la configuración de un workflow existente (settings y crossdock). ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"AddressInput":{"description":"Dirección de origen o destino. Se puede enviar de **tres formas mutuamente excluyentes**:\n\n| Modo | Qué enviar | Comportamiento |\n|------|-----------|----------------|\n| **1. Dirección existente** | solo `id` | Reutiliza una dirección ya creada, tal cual está. |\n| **2. Lugar guardado** | solo `place_id` | Copia automáticamente todos los datos desde el lugar. |\n| **3. Dirección nueva** | objeto completo | Crea una dirección nueva. |\n\n**Reglas de exclusión:**\n- `id` y `place_id` son excluyentes entre sí.\n- En el modo 3, la ubicación se indica por IDs internos (`city_id`) **o** por nombres (`city` + `state` + `country`).","oneOf":[{"$ref":"#/components/schemas/AddressByIdInput"},{"$ref":"#/components/schemas/AddressByPlaceInput"},{"$ref":"#/components/schemas/AddressNewInput"}]},"AddressByIdInput":{"title":"1. Reutilizar dirección existente (id)","description":"Reutiliza una dirección ya creada. Se usa exactamente como está; no se modifica ningún campo.","required":["id"],"properties":{"id":{"description":"ID de una dirección existente.","type":"string"}},"type":"object"},"AddressByPlaceInput":{"title":"2. Reutilizar lugar guardado (place_id)","description":"Reutiliza un lugar guardado. Todos los datos se copian automáticamente desde el lugar.","required":["place_id"],"properties":{"place_id":{"description":"ID del lugar guardado (con prefijo `ple_`). Debe existir en la lista de lugares de la organización.","type":"string"}},"type":"object"},"AddressNewInput":{"title":"3. Dirección nueva (objeto completo)","description":"Crea una dirección nueva. La ubicación se puede indicar de dos formas:\n- **Por IDs internos:** envía `city_id` (y opcionalmente `state_id` / `country_id`).\n- **Por nombres:** envía `city`, `state` y `country` (código ISO).","required":["name","street","street_number"],"properties":{"name":{"description":"Nombre del destinatario/remitente.","type":"string","maxLength":100},"street":{"description":"Nombre de la calle.","type":"string","maxLength":100},"street_number":{"description":"Altura/número.","type":"string","maxLength":10},"floor":{"description":"Piso (opcional).","type":"string","maxLength":5,"nullable":true},"apartment":{"description":"Departamento (opcional).","type":"string","maxLength":10,"nullable":true},"reference":{"description":"Referencia adicional (opcional).","type":"string","maxLength":255,"nullable":true},"city_id":{"description":"ID interno de la ciudad. Obligatorio si no se envía `city`, `state` y `country`.","type":"integer"},"city":{"description":"Nombre de la ciudad. Obligatorio si no se envía `city_id`.","type":"string"},"state_id":{"description":"ID interno de la provincia/estado (opcional).","type":"integer"},"state":{"description":"Nombre de la provincia/estado.","type":"string"},"country_id":{"description":"ID interno del país (opcional).","type":"integer"},"country":{"description":"Código ISO del país (ej: AR, MX, CL).","type":"string"},"zipcode":{"description":"Código postal (opcional).","type":"string","nullable":true},"phone":{"description":"Teléfono en formato E.164 (opcional).","type":"string","nullable":true},"email":{"description":"Email de contacto (opcional).","type":"string","format":"email","nullable":true},"document_type":{"description":"Código del tipo de documento (opcional).","type":"string","nullable":true},"document_number":{"description":"Número de documento (obligatorio si se envía `document_type`).","type":"string","nullable":true},"geo_latitude":{"description":"Latitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":90,"minimum":-90,"nullable":true},"geo_longitude":{"description":"Longitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":180,"minimum":-180,"nullable":true}},"type":"object"},"WorkflowSetting":{"description":"Configuración de un paso del workflow (step settings)","properties":{"step_code":{"description":"Código del step del blueprint.","type":"string"},"requirements_start":{"description":"Requisitos personalizados para iniciar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true},"requirements_complete":{"description":"Requisitos personalizados para completar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true},"requirements_fail":{"description":"Requisitos personalizados para fallar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"Workflow":{"description":"Workflow que agrupa las tareas de un envío o proceso logístico","properties":{"id":{"description":"Identificador del workflow.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"current_status":{"description":"Estado actual del workflow.","type":"string"},"blueprint":{"description":"Blueprint que define la estructura del workflow. Puede ser null si el blueprint fue eliminado.","properties":{"id":{"type":"integer"},"code":{"type":"string"},"steps":{"description":"Pasos del blueprint. Solo presente en respuestas de resumen (WorkflowSummaryResource).","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"data":{"description":"Datos adicionales asociados al workflow (estructura variable según el blueprint).","type":"object","nullable":true},"tasks":{"description":"Tareas del workflow. Con include_tasks=1 retorna objetos `Task` completos; sin ese parámetro retorna resúmenes `TaskSummary` (subset reducido).","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Task"}},{"type":"array","items":{"$ref":"#/components/schemas/TaskSummary"}}]}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"},"TaskSummary":{"description":"Resumen reducido de una tarea, retornado en contextos de workflow sin include_tasks=1.","properties":{"id":{"description":"ULID de la tarea.","type":"string"},"internal_id":{"description":"ID numérico interno de la tarea.","type":"integer"},"carrier":{"properties":{"id":{"type":"integer"}},"type":"object"},"shipment":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true}},"type":"object","nullable":true},"step":{"properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de tipo pickup.","type":"boolean"},"status":{"properties":{"id":{"type":"integer"},"code":{"type":"string"}},"type":"object"}},"type":"object"}}},"paths":{"/workflows/{workflow}":{"put":{"tags":["Workflows"],"summary":"Actualizar workflow","description":"Actualiza la configuración de un workflow existente (settings y crossdock).","operationId":"updateWorkflow","parameters":[{"name":"workflow","in":"path","description":"ID del workflow","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"crossdock":{"$ref":"#/components/schemas/AddressInput"},"settings":{"description":"Configuraciones personalizadas por step.","type":"array","items":{"$ref":"#/components/schemas/WorkflowSetting"}}},"type":"object"}}}},"responses":{"200":{"description":"Workflow actualizado","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"workflow":{"$ref":"#/components/schemas/Workflow"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Workflow no encontrado"},"422":{"description":"Error de validación"}}}}}} ``` ## Cancelar workflow > Cancela un workflow y todas sus tareas pendientes. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Workflow":{"description":"Workflow que agrupa las tareas de un envío o proceso logístico","properties":{"id":{"description":"Identificador del workflow.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"current_status":{"description":"Estado actual del workflow.","type":"string"},"blueprint":{"description":"Blueprint que define la estructura del workflow. Puede ser null si el blueprint fue eliminado.","properties":{"id":{"type":"integer"},"code":{"type":"string"},"steps":{"description":"Pasos del blueprint. Solo presente en respuestas de resumen (WorkflowSummaryResource).","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"data":{"description":"Datos adicionales asociados al workflow (estructura variable según el blueprint).","type":"object","nullable":true},"tasks":{"description":"Tareas del workflow. Con include_tasks=1 retorna objetos `Task` completos; sin ese parámetro retorna resúmenes `TaskSummary` (subset reducido).","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Task"}},{"type":"array","items":{"$ref":"#/components/schemas/TaskSummary"}}]}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"},"TaskSummary":{"description":"Resumen reducido de una tarea, retornado en contextos de workflow sin include_tasks=1.","properties":{"id":{"description":"ULID de la tarea.","type":"string"},"internal_id":{"description":"ID numérico interno de la tarea.","type":"integer"},"carrier":{"properties":{"id":{"type":"integer"}},"type":"object"},"shipment":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true}},"type":"object","nullable":true},"step":{"properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de tipo pickup.","type":"boolean"},"status":{"properties":{"id":{"type":"integer"},"code":{"type":"string"}},"type":"object"}},"type":"object"}}},"paths":{"/workflows/{workflow}/cancel":{"post":{"tags":["Workflows"],"summary":"Cancelar workflow","description":"Cancela un workflow y todas sus tareas pendientes.","operationId":"cancelWorkflow","parameters":[{"name":"workflow","in":"path","description":"ID del workflow","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Workflow cancelado","content":{"application/json":{"schema":{"properties":{"data":{"properties":{"workflow":{"$ref":"#/components/schemas/Workflow"}},"type":"object"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Workflow no encontrado"}}}}}} ``` ## Esquemas ## The Workflow object ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Workflow":{"description":"Workflow que agrupa las tareas de un envío o proceso logístico","properties":{"id":{"description":"Identificador del workflow.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"current_status":{"description":"Estado actual del workflow.","type":"string"},"blueprint":{"description":"Blueprint que define la estructura del workflow. Puede ser null si el blueprint fue eliminado.","properties":{"id":{"type":"integer"},"code":{"type":"string"},"steps":{"description":"Pasos del blueprint. Solo presente en respuestas de resumen (WorkflowSummaryResource).","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"data":{"description":"Datos adicionales asociados al workflow (estructura variable según el blueprint).","type":"object","nullable":true},"tasks":{"description":"Tareas del workflow. Con include_tasks=1 retorna objetos `Task` completos; sin ese parámetro retorna resúmenes `TaskSummary` (subset reducido).","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Task"}},{"type":"array","items":{"$ref":"#/components/schemas/TaskSummary"}}]}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"},"TaskSummary":{"description":"Resumen reducido de una tarea, retornado en contextos de workflow sin include_tasks=1.","properties":{"id":{"description":"ULID de la tarea.","type":"string"},"internal_id":{"description":"ID numérico interno de la tarea.","type":"integer"},"carrier":{"properties":{"id":{"type":"integer"}},"type":"object"},"shipment":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true}},"type":"object","nullable":true},"step":{"properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de tipo pickup.","type":"boolean"},"status":{"properties":{"id":{"type":"integer"},"code":{"type":"string"}},"type":"object"}},"type":"object"}}}} ``` ## The Task object ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}}} ``` # Tareas ## Endpoints ## Crear tarea > Crea una nueva tarea independiente (no asociada a un workflow). ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Gestión de tareas"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"AddressInput":{"description":"Dirección de origen o destino. Se puede enviar de **tres formas mutuamente excluyentes**:\n\n| Modo | Qué enviar | Comportamiento |\n|------|-----------|----------------|\n| **1. Dirección existente** | solo `id` | Reutiliza una dirección ya creada, tal cual está. |\n| **2. Lugar guardado** | solo `place_id` | Copia automáticamente todos los datos desde el lugar. |\n| **3. Dirección nueva** | objeto completo | Crea una dirección nueva. |\n\n**Reglas de exclusión:**\n- `id` y `place_id` son excluyentes entre sí.\n- En el modo 3, la ubicación se indica por IDs internos (`city_id`) **o** por nombres (`city` + `state` + `country`).","oneOf":[{"$ref":"#/components/schemas/AddressByIdInput"},{"$ref":"#/components/schemas/AddressByPlaceInput"},{"$ref":"#/components/schemas/AddressNewInput"}]},"AddressByIdInput":{"title":"1. Reutilizar dirección existente (id)","description":"Reutiliza una dirección ya creada. Se usa exactamente como está; no se modifica ningún campo.","required":["id"],"properties":{"id":{"description":"ID de una dirección existente.","type":"string"}},"type":"object"},"AddressByPlaceInput":{"title":"2. Reutilizar lugar guardado (place_id)","description":"Reutiliza un lugar guardado. Todos los datos se copian automáticamente desde el lugar.","required":["place_id"],"properties":{"place_id":{"description":"ID del lugar guardado (con prefijo `ple_`). Debe existir en la lista de lugares de la organización.","type":"string"}},"type":"object"},"AddressNewInput":{"title":"3. Dirección nueva (objeto completo)","description":"Crea una dirección nueva. La ubicación se puede indicar de dos formas:\n- **Por IDs internos:** envía `city_id` (y opcionalmente `state_id` / `country_id`).\n- **Por nombres:** envía `city`, `state` y `country` (código ISO).","required":["name","street","street_number"],"properties":{"name":{"description":"Nombre del destinatario/remitente.","type":"string","maxLength":100},"street":{"description":"Nombre de la calle.","type":"string","maxLength":100},"street_number":{"description":"Altura/número.","type":"string","maxLength":10},"floor":{"description":"Piso (opcional).","type":"string","maxLength":5,"nullable":true},"apartment":{"description":"Departamento (opcional).","type":"string","maxLength":10,"nullable":true},"reference":{"description":"Referencia adicional (opcional).","type":"string","maxLength":255,"nullable":true},"city_id":{"description":"ID interno de la ciudad. Obligatorio si no se envía `city`, `state` y `country`.","type":"integer"},"city":{"description":"Nombre de la ciudad. Obligatorio si no se envía `city_id`.","type":"string"},"state_id":{"description":"ID interno de la provincia/estado (opcional).","type":"integer"},"state":{"description":"Nombre de la provincia/estado.","type":"string"},"country_id":{"description":"ID interno del país (opcional).","type":"integer"},"country":{"description":"Código ISO del país (ej: AR, MX, CL).","type":"string"},"zipcode":{"description":"Código postal (opcional).","type":"string","nullable":true},"phone":{"description":"Teléfono en formato E.164 (opcional).","type":"string","nullable":true},"email":{"description":"Email de contacto (opcional).","type":"string","format":"email","nullable":true},"document_type":{"description":"Código del tipo de documento (opcional).","type":"string","nullable":true},"document_number":{"description":"Número de documento (obligatorio si se envía `document_type`).","type":"string","nullable":true},"geo_latitude":{"description":"Latitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":90,"minimum":-90,"nullable":true},"geo_longitude":{"description":"Longitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":180,"minimum":-180,"nullable":true}},"type":"object"},"PackageInput":{"description":"Paquete a incluir en el envío o tarea. Cada medida (peso y dimensiones) se puede enviar de dos formas:\n- **Valor normalizado:** `grams` (gramos), `length`/`width`/`height` (centímetros). El sistema lo guarda tal cual.\n- **Valor con unidad:** `original_weight` + `weight_unit` (y los `original_*` + `*_unit` para dimensiones). El sistema normaliza automáticamente y conserva el valor original.\n\n**Si se envía `id`:** se reutiliza un paquete existente y los demás campos no son necesarios.\n\n**Si no se envía `id`:** `length`, `width` y `height` son obligatorios. El peso debe enviarse como `grams` **o** `original_weight` + `weight_unit`.\n\nUnidades soportadas:\n- Peso: `g`, `kg`, `mg`, `lbs`\n- Dimensiones: `cm`, `m`, `mm`, `in`\n- Temperatura: `celsius`, `fahrenheit`\n\nLa entrada es tolerante: se aceptan mayúsculas, símbolos y abreviaturas equivalentes\n(`KG`, `°C`, `F`, `inches`, `m3`, `m³`, `lt`), y el sistema las normaliza. Lo que se\n**guarda y se devuelve** es siempre el valor canónico en texto plano de la lista de arriba.","properties":{"id":{"description":"ID del paquete existente. Si se envía, los demás campos no son necesarios.","type":"integer"},"external_reference":{"description":"Referencia externa (opcional).","type":"string","maxLength":50,"nullable":true},"description":{"description":"Descripción del paquete (opcional).","type":"string","maxLength":190,"nullable":true},"label_code":{"description":"Código de etiqueta del paquete.","type":"string","maxLength":20},"length":{"description":"Largo en centímetros (normalizado).","type":"integer"},"width":{"description":"Ancho en centímetros (normalizado).","type":"integer"},"height":{"description":"Alto en centímetros (normalizado).","type":"integer"},"original_length":{"description":"Largo en la unidad original.","type":"number"},"length_unit":{"description":"Unidad del largo original.","type":"string","enum":["cm","m","mm","in"]},"original_width":{"description":"Ancho en la unidad original.","type":"number"},"width_unit":{"description":"Unidad del ancho original.","type":"string","enum":["cm","m","mm","in"]},"original_height":{"description":"Alto en la unidad original.","type":"number"},"height_unit":{"description":"Unidad del alto original.","type":"string","enum":["cm","m","mm","in"]},"grams":{"description":"Peso en gramos (normalizado). Opcional si se envía original_weight + weight_unit.","type":"integer"},"original_weight":{"description":"Peso en la unidad original. Opcional si se envía grams.","type":"number"},"weight_unit":{"description":"Unidad del peso original. Requerido si se envía original_weight.","type":"string","enum":["g","kg","mg","lbs"]},"declared_value_amount":{"description":"Valor declarado del paquete (para seguros/aduana). Por defecto 0.","type":"number","format":"float","nullable":true},"declared_value_currency":{"description":"Moneda del valor declarado (ISO 4217). Si no se especifica, se usa la moneda por defecto de la organización.","type":"string","maxLength":4,"nullable":true},"un_code":{"description":"Código UN de mercancía peligrosa.","type":"string"},"classification":{"description":"Clasificación del paquete.","type":"string"},"is_flammable":{"description":"Si el paquete es inflamable.","type":"boolean","default":false},"is_corrosive":{"description":"Si el paquete es corrosivo.","type":"boolean","default":false},"is_fragile":{"description":"Si el paquete es frágil.","type":"boolean","default":false},"temperature_min":{"description":"Temperatura mínima de transporte en grados Celsius (normalizado).","type":"number"},"temperature_max":{"description":"Temperatura máxima de transporte en grados Celsius (normalizado).","type":"number"},"original_temperature_min":{"description":"Temperatura mínima en la unidad original.","type":"number"},"temperature_min_unit":{"description":"Unidad de temperatura mínima original.","type":"string","enum":["celsius","fahrenheit"]},"original_temperature_max":{"description":"Temperatura máxima en la unidad original.","type":"number"},"temperature_max_unit":{"description":"Unidad de temperatura máxima original.","type":"string","enum":["celsius","fahrenheit"]}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/tasks":{"post":{"tags":["Tasks"],"summary":"Crear tarea","description":"Crea una nueva tarea independiente (no asociada a un workflow).","operationId":"createTask","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["address","packages"],"properties":{"address":{"$ref":"#/components/schemas/AddressInput"},"packages":{"description":"Paquetes de la tarea.","type":"array","items":{"$ref":"#/components/schemas/PackageInput"},"minItems":1},"external_reference":{"description":"Referencia externa de la tarea.","type":"string","nullable":true},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas adicionales para el conductor.","type":"string","nullable":true},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true},"time_windows":{"description":"Ventanas de tiempo.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"},"nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Tarea creada","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"422":{"description":"Error de validación"}}}}}} ``` ## Listar tareas > Retorna un listado paginado de tareas de la organización, con soporte para filtros y búsqueda. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Gestión de tareas"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"},"Pagination":{"description":"Metadatos de paginación","properties":{"total":{"description":"Total de registros.","type":"integer"},"per_page":{"description":"Registros por página.","type":"integer"},"current_page":{"description":"Página actual.","type":"integer"},"last_page":{"description":"Última página.","type":"integer"},"from":{"description":"Índice del primer registro de la página.","type":"integer"},"to":{"description":"Índice del último registro de la página.","type":"integer"}},"type":"object"}}},"paths":{"/tasks":{"get":{"tags":["Tasks"],"summary":"Listar tareas","description":"Retorna un listado paginado de tareas de la organización, con soporte para filtros y búsqueda.","operationId":"searchTasks","parameters":[{"name":"shift_date","in":"query","description":"Filtrar por fecha (formato YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date"}},{"name":"filter[global]","in":"query","description":"Búsqueda global en texto libre (mínimo 3 caracteres).","required":false,"schema":{"type":"string","minLength":3}},{"name":"filter[status]","in":"query","description":"Filtrar por ID de estado.","required":false,"schema":{"type":"integer"}},{"name":"filter[pickup]","in":"query","description":"Filtrar solo tareas de pickup.","required":false,"schema":{"type":"boolean"}},{"name":"filter[assigned]","in":"query","description":"Filtrar tareas asignadas al usuario autenticado.","required":false,"schema":{"type":"boolean"}},{"name":"filter[blueprint]","in":"query","description":"Filtrar por ID o código del blueprint.","required":false,"schema":{"type":"string"}},{"name":"filter[shipment]","in":"query","description":"Filtrar por ID del envío.","required":false,"schema":{"type":"string"}},{"name":"filter[workflow]","in":"query","description":"Filtrar por ID del workflow.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista paginada de tareas","content":{"application/json":{"schema":{"properties":{"data":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"links":{"properties":{"first":{"type":"string","format":"uri","nullable":true},"last":{"type":"string","format":"uri","nullable":true},"prev":{"type":"string","format":"uri","nullable":true},"next":{"type":"string","format":"uri","nullable":true}},"type":"object"},"meta":{"$ref":"#/components/schemas/Pagination"}},"type":"object"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"}}}}}} ``` ## Obtener tarea > Obtiene los detalles completos de una tarea. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Gestión de tareas"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/tasks/{task}":{"get":{"tags":["Tasks"],"summary":"Obtener tarea","description":"Obtiene los detalles completos de una tarea.","operationId":"getTask","parameters":[{"name":"task","in":"path","description":"ID de la tarea","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tarea obtenida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Tarea no encontrada"}}}}}} ``` ## Obtener adjunto de tarea > Retorna el contenido de un adjunto específico de la tarea, codificado en base64. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Gestión de tareas"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Attachment":{"description":"Adjunto con contenido en base64","properties":{"id":{"type":"string","format":"uuid"},"group":{"type":"string"},"name":{"type":"string"},"mime_type":{"type":"string"},"size":{"description":"Tamaño en bytes.","type":"integer"},"created_at":{"type":"string","format":"date-time"},"content":{"description":"Contenido del archivo codificado en base64.","type":"string","format":"byte"}},"type":"object"}}},"paths":{"/tasks/{task}/attachments/{attachment}":{"get":{"tags":["Tasks"],"summary":"Obtener adjunto de tarea","description":"Retorna el contenido de un adjunto específico de la tarea, codificado en base64.","operationId":"getTaskAttachment","parameters":[{"name":"task","in":"path","description":"ID de la tarea","required":true,"schema":{"type":"string"}},{"name":"attachment","in":"path","description":"UUID del adjunto","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Adjunto obtenido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attachment"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Adjunto no encontrado"}}}}}} ``` ## Cancelar tarea > Cancela una tarea. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Gestión de tareas"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/tasks/{task}/cancel":{"post":{"tags":["Tasks"],"summary":"Cancelar tarea","description":"Cancela una tarea.","operationId":"cancelTask","parameters":[{"name":"task","in":"path","description":"ID de la tarea","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"properties":{"metadata":{"description":"Metadata opcional para el evento de cancelación.","type":"object","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Tarea cancelada","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Tarea no encontrada"}}}}}} ``` ## Esquemas ## The Task object ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}}} ``` ## The Requirement object ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"}}}} ``` # Rutas ## Endpoints ## Listar rutas > Retorna un listado paginado de rutas de la organización. Por defecto excluye rutas en estado \`draft\` y \`finished\`. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Routes","description":"Gestión de rutas"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"RouteSummary":{"description":"Resumen de una ruta para listados paginados","properties":{"id":{"type":"integer","format":"int64"},"external_id":{"type":"string","nullable":true},"shift_date":{"type":"string","format":"date"},"status":{"type":"string"},"facility":{"description":"Instalación bajo la que se planificó la ruta. `null` si la ruta no está asociada a ninguna.","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"driver":{"properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"vehicle":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"created_at":{"type":"string","format":"date-time"}},"type":"object"},"Pagination":{"description":"Metadatos de paginación","properties":{"total":{"description":"Total de registros.","type":"integer"},"per_page":{"description":"Registros por página.","type":"integer"},"current_page":{"description":"Página actual.","type":"integer"},"last_page":{"description":"Última página.","type":"integer"},"from":{"description":"Índice del primer registro de la página.","type":"integer"},"to":{"description":"Índice del último registro de la página.","type":"integer"}},"type":"object"}}},"paths":{"/routes":{"get":{"tags":["Routes"],"summary":"Listar rutas","description":"Retorna un listado paginado de rutas de la organización. Por defecto excluye rutas en estado `draft` y `finished`.","operationId":"getRoutes","parameters":[{"name":"status","in":"query","description":"Filtrar por estado(s). Puede ser un string (`status=published`) o un array (`status[]=published&status[]=started`).","required":false,"schema":{"oneOf":[{"type":"string","enum":["draft","published","blocked","started","finished"]},{"type":"array","items":{"type":"string","enum":["draft","published","blocked","started","finished"]}}]}},{"name":"created_from","in":"query","description":"Filtrar rutas creadas desde esta fecha (ISO 8601).","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","description":"Filtrar rutas creadas hasta esta fecha (ISO 8601).","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"facility","in":"query","description":"Filtrar por instalación(es) de la ruta. Puede ser un string (`facility=fac_01JTQZ8KPME5X3N7WVYHF2RD4K`) o un array (`facility[]=...&facility[]=...`). Acepta el ID de la instalación (`fac_...`) o su ID interno. Las rutas sin instalación asociada quedan excluidas al aplicar este filtro.","required":false,"schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}],"responses":{"200":{"description":"Lista paginada de rutas","content":{"application/json":{"schema":{"properties":{"routes":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RouteSummary"}},"links":{"properties":{"first":{"type":"string","format":"uri","nullable":true},"last":{"type":"string","format":"uri","nullable":true},"prev":{"type":"string","format":"uri","nullable":true},"next":{"type":"string","format":"uri","nullable":true}},"type":"object"},"meta":{"$ref":"#/components/schemas/Pagination"}},"type":"object"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"}}}}}} ``` ## Obtener ruta > Obtiene los detalles completos de una ruta incluyendo vehículo, conductor y tareas. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Routes","description":"Gestión de rutas"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Route":{"description":"Ruta de reparto con sus tareas y datos del vehículo y conductor","properties":{"id":{"description":"ID interno de la ruta.","type":"integer","format":"int64"},"external_id":{"description":"ID externo de la ruta.","type":"string","nullable":true},"shift_date":{"description":"Fecha de la ruta.","type":"string","format":"date"},"shift_sequence":{"description":"Secuencia de la ruta (número de ruta para un vehículo y fecha).","type":"integer"},"status":{"description":"Estado de la ruta.","type":"string","enum":["draft","published","blocked","started","finished"]},"carrier":{"description":"Organización transportista","properties":{"id":{"description":"ID del transportista.","type":"string"}},"type":"object"},"facility":{"description":"Instalación bajo la que se planificó la ruta. `null` si la ruta no está asociada a ninguna.","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"vehicle":{"description":"Vehículo asignado a la ruta","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"vehicle_type":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object","nullable":true},"driver":{"description":"Conductor asignado a la ruta","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"},"phone":{"description":"Teléfono en formato E.164.","type":"string"},"email":{"type":"string"},"is_driver_on_duty":{"description":"Indica si el conductor está en servicio activo.","type":"boolean"}},"type":"object","nullable":true},"encoded_polyline":{"description":"Polyline codificada del recorrido.","type":"string","nullable":true},"tasks":{"description":"Tareas de la ruta. Sin agrupamiento: array de objetos con `sequence_number` y `task`. Con `show_grouped=1`: objeto donde cada clave es el `grouping_hash` del grupo y el valor es un array de esos mismos objetos.","oneOf":[{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}},{"type":"object","additionalProperties":{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}}}]},"created_at":{"type":"string","format":"date-time"},"published_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/routes/{route}":{"get":{"tags":["Routes"],"summary":"Obtener ruta","description":"Obtiene los detalles completos de una ruta incluyendo vehículo, conductor y tareas.","operationId":"getRoute","parameters":[{"name":"route","in":"path","description":"ID de la ruta","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"show_grouped","in":"query","description":"Si es `1`, el campo `tasks` se retorna como un objeto donde las claves son valores de `grouping_hash` y cada valor es un array de tareas con su número de secuencia, en lugar de un array plano.","required":false,"schema":{"type":"integer","default":0,"enum":[0,1]}}],"responses":{"200":{"description":"Ruta obtenida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Route"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Ruta no encontrada"}}}}}} ``` ## Crear ruta > Crea una nueva ruta de reparto, opcionalmente con vehículo, conductor y tareas iniciales. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Routes","description":"Gestión de rutas"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Route":{"description":"Ruta de reparto con sus tareas y datos del vehículo y conductor","properties":{"id":{"description":"ID interno de la ruta.","type":"integer","format":"int64"},"external_id":{"description":"ID externo de la ruta.","type":"string","nullable":true},"shift_date":{"description":"Fecha de la ruta.","type":"string","format":"date"},"shift_sequence":{"description":"Secuencia de la ruta (número de ruta para un vehículo y fecha).","type":"integer"},"status":{"description":"Estado de la ruta.","type":"string","enum":["draft","published","blocked","started","finished"]},"carrier":{"description":"Organización transportista","properties":{"id":{"description":"ID del transportista.","type":"string"}},"type":"object"},"facility":{"description":"Instalación bajo la que se planificó la ruta. `null` si la ruta no está asociada a ninguna.","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"vehicle":{"description":"Vehículo asignado a la ruta","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"vehicle_type":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object","nullable":true},"driver":{"description":"Conductor asignado a la ruta","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"},"phone":{"description":"Teléfono en formato E.164.","type":"string"},"email":{"type":"string"},"is_driver_on_duty":{"description":"Indica si el conductor está en servicio activo.","type":"boolean"}},"type":"object","nullable":true},"encoded_polyline":{"description":"Polyline codificada del recorrido.","type":"string","nullable":true},"tasks":{"description":"Tareas de la ruta. Sin agrupamiento: array de objetos con `sequence_number` y `task`. Con `show_grouped=1`: objeto donde cada clave es el `grouping_hash` del grupo y el valor es un array de esos mismos objetos.","oneOf":[{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}},{"type":"object","additionalProperties":{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}}}]},"created_at":{"type":"string","format":"date-time"},"published_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/routes":{"post":{"tags":["Routes"],"summary":"Crear ruta","description":"Crea una nueva ruta de reparto, opcionalmente con vehículo, conductor y tareas iniciales.","operationId":"createRoute","requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vehicle_id":{"description":"ID del vehículo a asignar.","type":"integer","nullable":true},"driver_id":{"description":"ID del conductor a asignar.","type":"integer","nullable":true},"shift_date":{"description":"Fecha de la ruta.","type":"string","format":"date"},"external_id":{"description":"ID externo de la ruta.","type":"string","nullable":true},"description":{"description":"Descripción de la ruta.","type":"string","nullable":true},"facility_id":{"description":"Instalación bajo la que opera la ruta, con su ID (`fac_...`). Si se omite, se usa la instalación más antigua de la organización.","type":"string","nullable":true},"tasks":{"description":"Tareas a agregar a la ruta (opcionales al crear).","type":"array","items":{"properties":{"id":{"description":"ID de la tarea.","type":"string"},"position":{"description":"Posición en la ruta.","type":"integer","nullable":true}},"type":"object"},"nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Ruta creada","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"route":{"$ref":"#/components/schemas/Route"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"422":{"description":"Error de validación"}}}}}} ``` ## Agregar tareas a la ruta > Agrega una o más tareas a una ruta. Cada tarea se identifica por su ID.\ > Las tareas del mismo workflow se incluyen automáticamente. Las tareas en estado final (completada, fallada, cancelada) se reportan en \`tasks\_in\_final\_status\` pero no se agregan. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Routes","description":"Gestión de rutas"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Route":{"description":"Ruta de reparto con sus tareas y datos del vehículo y conductor","properties":{"id":{"description":"ID interno de la ruta.","type":"integer","format":"int64"},"external_id":{"description":"ID externo de la ruta.","type":"string","nullable":true},"shift_date":{"description":"Fecha de la ruta.","type":"string","format":"date"},"shift_sequence":{"description":"Secuencia de la ruta (número de ruta para un vehículo y fecha).","type":"integer"},"status":{"description":"Estado de la ruta.","type":"string","enum":["draft","published","blocked","started","finished"]},"carrier":{"description":"Organización transportista","properties":{"id":{"description":"ID del transportista.","type":"string"}},"type":"object"},"facility":{"description":"Instalación bajo la que se planificó la ruta. `null` si la ruta no está asociada a ninguna.","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"vehicle":{"description":"Vehículo asignado a la ruta","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"vehicle_type":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object","nullable":true},"driver":{"description":"Conductor asignado a la ruta","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"},"phone":{"description":"Teléfono en formato E.164.","type":"string"},"email":{"type":"string"},"is_driver_on_duty":{"description":"Indica si el conductor está en servicio activo.","type":"boolean"}},"type":"object","nullable":true},"encoded_polyline":{"description":"Polyline codificada del recorrido.","type":"string","nullable":true},"tasks":{"description":"Tareas de la ruta. Sin agrupamiento: array de objetos con `sequence_number` y `task`. Con `show_grouped=1`: objeto donde cada clave es el `grouping_hash` del grupo y el valor es un array de esos mismos objetos.","oneOf":[{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}},{"type":"object","additionalProperties":{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}}}]},"created_at":{"type":"string","format":"date-time"},"published_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/routes/{route}/tasks/add":{"post":{"tags":["Routes"],"summary":"Agregar tareas a la ruta","description":"Agrega una o más tareas a una ruta. Cada tarea se identifica por su ID.\nLas tareas del mismo workflow se incluyen automáticamente. Las tareas en estado final (completada, fallada, cancelada) se reportan en `tasks_in_final_status` pero no se agregan.","operationId":"addTasksToRoute","parameters":[{"name":"route","in":"path","description":"ID de la ruta","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["tasks"],"properties":{"tasks":{"description":"Tareas a agregar a la ruta","type":"array","items":{"required":["id"],"properties":{"id":{"description":"ID numérico o ULID de la tarea.","type":"string"},"position":{"description":"Posición deseada en la secuencia (opcional).","type":"integer","minimum":1,"nullable":true}},"type":"object"},"minItems":1}},"type":"object"}}}},"responses":{"200":{"description":"Tareas agregadas","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"route":{"$ref":"#/components/schemas/Route"},"tasks_in_final_status":{"description":"Tareas que no pudieron agregarse por estar en estado final.","type":"array","items":{"properties":{"task_id":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Ruta no encontrada"},"422":{"description":"Tarea no encontrada o no pertenece a la organización"}}}}}} ``` ## Quitar tareas de la ruta > Elimina una o más tareas de una ruta. Las tareas se identifican por su ID. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Routes","description":"Gestión de rutas"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Route":{"description":"Ruta de reparto con sus tareas y datos del vehículo y conductor","properties":{"id":{"description":"ID interno de la ruta.","type":"integer","format":"int64"},"external_id":{"description":"ID externo de la ruta.","type":"string","nullable":true},"shift_date":{"description":"Fecha de la ruta.","type":"string","format":"date"},"shift_sequence":{"description":"Secuencia de la ruta (número de ruta para un vehículo y fecha).","type":"integer"},"status":{"description":"Estado de la ruta.","type":"string","enum":["draft","published","blocked","started","finished"]},"carrier":{"description":"Organización transportista","properties":{"id":{"description":"ID del transportista.","type":"string"}},"type":"object"},"facility":{"description":"Instalación bajo la que se planificó la ruta. `null` si la ruta no está asociada a ninguna.","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"vehicle":{"description":"Vehículo asignado a la ruta","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"vehicle_type":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object","nullable":true},"driver":{"description":"Conductor asignado a la ruta","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"},"phone":{"description":"Teléfono en formato E.164.","type":"string"},"email":{"type":"string"},"is_driver_on_duty":{"description":"Indica si el conductor está en servicio activo.","type":"boolean"}},"type":"object","nullable":true},"encoded_polyline":{"description":"Polyline codificada del recorrido.","type":"string","nullable":true},"tasks":{"description":"Tareas de la ruta. Sin agrupamiento: array de objetos con `sequence_number` y `task`. Con `show_grouped=1`: objeto donde cada clave es el `grouping_hash` del grupo y el valor es un array de esos mismos objetos.","oneOf":[{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}},{"type":"object","additionalProperties":{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}}}]},"created_at":{"type":"string","format":"date-time"},"published_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/routes/{route}/tasks/remove":{"post":{"tags":["Routes"],"summary":"Quitar tareas de la ruta","description":"Elimina una o más tareas de una ruta. Las tareas se identifican por su ID.","operationId":"removeTasksFromRoute","parameters":[{"name":"route","in":"path","description":"ID de la ruta","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["tasks"],"properties":{"tasks":{"description":"Lista de IDs (numérico o ULID) de las tareas a quitar","type":"array","items":{"description":"ID numérico o ULID de la tarea.","type":"string"},"minItems":1}},"type":"object"}}}},"responses":{"200":{"description":"Tareas quitadas de la ruta","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"route":{"$ref":"#/components/schemas/Route"},"tasks_in_final_status":{"description":"Tareas que no pudieron quitarse por estar en estado final.","type":"array","items":{"properties":{"task_id":{"type":"integer"},"message":{"type":"string"}},"type":"object"}}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Ruta no encontrada"},"422":{"description":"Una o más tareas no existen o no pertenecen a la organización"}}}}}} ``` ## Publicar ruta > Publica una ruta para que quede disponible al conductor. La ruta debe tener un conductor asignado y no estar publicada previamente. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Routes","description":"Gestión de rutas"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Route":{"description":"Ruta de reparto con sus tareas y datos del vehículo y conductor","properties":{"id":{"description":"ID interno de la ruta.","type":"integer","format":"int64"},"external_id":{"description":"ID externo de la ruta.","type":"string","nullable":true},"shift_date":{"description":"Fecha de la ruta.","type":"string","format":"date"},"shift_sequence":{"description":"Secuencia de la ruta (número de ruta para un vehículo y fecha).","type":"integer"},"status":{"description":"Estado de la ruta.","type":"string","enum":["draft","published","blocked","started","finished"]},"carrier":{"description":"Organización transportista","properties":{"id":{"description":"ID del transportista.","type":"string"}},"type":"object"},"facility":{"description":"Instalación bajo la que se planificó la ruta. `null` si la ruta no está asociada a ninguna.","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"vehicle":{"description":"Vehículo asignado a la ruta","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"vehicle_type":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object","nullable":true},"driver":{"description":"Conductor asignado a la ruta","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"},"phone":{"description":"Teléfono en formato E.164.","type":"string"},"email":{"type":"string"},"is_driver_on_duty":{"description":"Indica si el conductor está en servicio activo.","type":"boolean"}},"type":"object","nullable":true},"encoded_polyline":{"description":"Polyline codificada del recorrido.","type":"string","nullable":true},"tasks":{"description":"Tareas de la ruta. Sin agrupamiento: array de objetos con `sequence_number` y `task`. Con `show_grouped=1`: objeto donde cada clave es el `grouping_hash` del grupo y el valor es un array de esos mismos objetos.","oneOf":[{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}},{"type":"object","additionalProperties":{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}}}]},"created_at":{"type":"string","format":"date-time"},"published_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/routes/{route}/publish":{"post":{"tags":["Routes"],"summary":"Publicar ruta","description":"Publica una ruta para que quede disponible al conductor. La ruta debe tener un conductor asignado y no estar publicada previamente.","operationId":"publishRoute","parameters":[{"name":"route","in":"path","description":"ID de la ruta","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Ruta publicada","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"route":{"$ref":"#/components/schemas/Route"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Ruta no encontrada"},"406":{"description":"La ruta no puede publicarse (ya publicada o sin conductor)"}}}}}} ``` ## Esquemas ## The Route object ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Route":{"description":"Ruta de reparto con sus tareas y datos del vehículo y conductor","properties":{"id":{"description":"ID interno de la ruta.","type":"integer","format":"int64"},"external_id":{"description":"ID externo de la ruta.","type":"string","nullable":true},"shift_date":{"description":"Fecha de la ruta.","type":"string","format":"date"},"shift_sequence":{"description":"Secuencia de la ruta (número de ruta para un vehículo y fecha).","type":"integer"},"status":{"description":"Estado de la ruta.","type":"string","enum":["draft","published","blocked","started","finished"]},"carrier":{"description":"Organización transportista","properties":{"id":{"description":"ID del transportista.","type":"string"}},"type":"object"},"facility":{"description":"Instalación bajo la que se planificó la ruta. `null` si la ruta no está asociada a ninguna.","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"vehicle":{"description":"Vehículo asignado a la ruta","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"vehicle_type":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object","nullable":true},"driver":{"description":"Conductor asignado a la ruta","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"},"phone":{"description":"Teléfono en formato E.164.","type":"string"},"email":{"type":"string"},"is_driver_on_duty":{"description":"Indica si el conductor está en servicio activo.","type":"boolean"}},"type":"object","nullable":true},"encoded_polyline":{"description":"Polyline codificada del recorrido.","type":"string","nullable":true},"tasks":{"description":"Tareas de la ruta. Sin agrupamiento: array de objetos con `sequence_number` y `task`. Con `show_grouped=1`: objeto donde cada clave es el `grouping_hash` del grupo y el valor es un array de esos mismos objetos.","oneOf":[{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}},{"type":"object","additionalProperties":{"type":"array","items":{"properties":{"sequence_number":{"type":"integer"},"task":{"$ref":"#/components/schemas/Task"}},"type":"object"}}}]},"created_at":{"type":"string","format":"date-time"},"published_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}}} ``` ## The Task object ```json {"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, celsius para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, mg, lbs).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en grados Celsius.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"description":"Unidad original (celsius, fahrenheit).","type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true},"declared_value_amount":{"type":"number","format":"float"},"declared_value_currency":{"type":"string","nullable":true}},"type":"object"},"Merchant":{"description":"Comercio asociado a una tarea o envío","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","nullable":true}},"type":"object"}}}} ``` # Usuarios ## Endpoints # Brand Kit {% content-ref url="/pages/LvC3WVHSRjTYb6xguQ8p" %} [Colores](/brand/colores) {% endcontent-ref %} {% content-ref url="/pages/ipO44K1gbKK5XWcc05tG" %} [Logos](/brand/logos) {% endcontent-ref %} # Colores

Porcentaje de uso de cada color en el sistema gráfico

## Colores de nuestra paleta | Color | Nombre | HEX | RGB | CMYK | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------- | ----------- | ---------- | | ![](https://2728694031-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvapRjK1iJDRSdjEDOsdS%2Fuploads%2FP6l3gKdHaingS8EHnL1Y%2Fwhite.png?alt=media\&token=7a5bc24a-9d9c-43ee-9414-6a66a93bc97b) | Blanco | #FFFFFF | 255,255,255 | 0,0,0,0 | | ![](https://2728694031-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvapRjK1iJDRSdjEDOsdS%2Fuploads%2Fn0ztKQRltkF9S8ti65ld%2Fgrey1.png?alt=media\&token=b47bf1dc-e85d-423e-ba48-76e9996d8321) | Gris 1 | #F3F5F8 | 243,245,248 | 2,0,0,3 | | ![](https://2728694031-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvapRjK1iJDRSdjEDOsdS%2Fuploads%2FQV4uV4L3yIJnxf5PS3Vh%2Fgrey2.png?alt=media\&token=cad18d58-7b91-4595-a46a-9764e6f2b168) | Gris 2 | #E5EBF4 | 229,235,244 | 4,0,0,6 | | ![](https://2728694031-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvapRjK1iJDRSdjEDOsdS%2Fuploads%2FuTy1C7CcQKOUxcqpkNDK%2Fgrey3.png?alt=media\&token=7f0f8194-b769-4359-9af0-272ba72b06da) | Gris 3 | #C5CDDD | 197,205,221 | 10,0,0,18 | | ![](https://2728694031-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvapRjK1iJDRSdjEDOsdS%2Fuploads%2FcR4yKsBrx3IgQ8IZbKGR%2Fdark.png?alt=media\&token=c5df6ca3-4cd4-4200-97de-1a2e6636e36c) | Oscuro | #172937 | 23,41,55 | 50,10,0,90 | | ![](https://2728694031-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvapRjK1iJDRSdjEDOsdS%2Fuploads%2FYxYU6jA7YdgjXj8dyCb4%2Fgreen.png?alt=media\&token=59c784b2-c3d0-4e58-b7f3-a26b70da2275) | Verde (Primario) | #14EFB6 | 20,239,182 | 65,0,50,0 | | ![](https://2728694031-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvapRjK1iJDRSdjEDOsdS%2Fuploads%2FzTrExbIy39j8Ew09STvc%2Fblack.png?alt=media\&token=f9641944-9725-4184-983b-dbe11c6d7e94) | Negro | #000000 | 0,0,0 | 0,0,0,100 | | ![](https://2728694031-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvapRjK1iJDRSdjEDOsdS%2Fuploads%2F4wd5IO27gjXVxkX0wJcZ%2Fblue.png?alt=media\&token=7ee3c1ac-ac8e-4f3a-a2d3-425aa7f7d9a0) | Azul | #3B4CEA | 59,76,234 | 90,80,0,0 | | ![](https://2728694031-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvapRjK1iJDRSdjEDOsdS%2Fuploads%2FOxKOJdc1yIgLt2SUHJvo%2Fmagenta.png?alt=media\&token=1164b73a-9dc2-4860-9bce-4de363cb2048) | Magenta | #FF5CE0 | 255,92,224 | 15,90,0,0 | # Logos ## Descargar logos {% embed url="" %} ### Logos completos

Logo a color en PNG

Logo monocromático en PNG

### Símbolo

Símbolo en fondo oscuro circular

Símbolo en fondo verde circular

Símbolo en fondo transparente

## Uso del logo

Area de seguridad

### Usos no permitidos

Usos no permitidos del logo

1. No comprimir el logo 2. No expandir el logo 3. No rotar el logo 4. No alterar el orden de elementos 5. No utilizar el wordmark sin el símbolo 6. No aplicar el logo en un color que no sea de la paleta de colores 7. No aplicar el logo donde el contraste impida su lectura 8. No aplicar sobre fondos que dificulten la legibilidad 9. No aplicar sobre fondos e imágenes complejas