> 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/tareas.md).

# 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`, `lbs`, `oz`\n- Dimensiones: `cm`, `m`, `in`, `ft`\n- Temperatura: `°C`, `°F`","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","in","ft"]},"original_width":{"description":"Ancho en la unidad original.","type":"number"},"width_unit":{"description":"Unidad del ancho original.","type":"string","enum":["cm","m","in","ft"]},"original_height":{"description":"Alto en la unidad original.","type":"number"},"height_unit":{"description":"Unidad del alto original.","type":"string","enum":["cm","m","in","ft"]},"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","lbs","oz"]},"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 °C (normalizado).","type":"number"},"temperature_max":{"description":"Temperatura máxima de transporte en °C (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":["°C","°F"]},"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":["°C","°F"]}},"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, °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":{"/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, °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"},"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, °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":{"/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, °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":{"/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, °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 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"}}}}
```