> For the complete documentation index, see [llms.txt](https://docs.zipnova.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zipnova.com/rutas/api/rutas.md).

# 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"},"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"}}],"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"},"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, °C 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, lbs, oz).","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 °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"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}},"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"},"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, °C 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, lbs, oz).","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 °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"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}},"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},"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"},"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, °C 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, lbs, oz).","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 °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"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}},"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"},"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, °C 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, lbs, oz).","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 °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"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}},"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"},"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, °C 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, lbs, oz).","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 °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"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}},"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"},"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, °C 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, lbs, oz).","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 °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"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}},"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, °C 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, lbs, oz).","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 °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"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}},"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"}}}}
```