> 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
## Create Task
> Creates a new task
```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Gestión de tareas"}],"servers":[{"url":"https://{organization}.routes.zipnova.com/api/v1","variables":{"organization":{"default":"mi-organizacion","description":"Organization subdomain"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","bearerFormat":"5|sdmnakj32e90ansaIKJNe20Jasaaxzaxx2","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á. No se modifica ningún dato. |\n| **2. Lugar guardado** | solo `place_id` | Copia automáticamente todos los datos (nombre, calle, contacto, documento, ciudad y coordenadas) desde el lugar. |\n| **3. Dirección nueva** | objeto completo | Crea una dirección nueva. `name`, `street`, `street_number` y la ubicación son obligatorios. |\n\n**Reglas de exclusión:**\n- `id` y `place_id` son excluyentes entre sí.\n- Si enviás `id` o `place_id`, **no** podés enviar `street`, `street_number`, `floor`, `apartment` ni `reference`.\n- En el modo 3, la ubicación se indica por IDs internos (`city_id`) **o** por nombres (`city` + `state` + `country`).\n","oneOf":[{"$ref":"#/components/schemas/AddressByIdInput"},{"$ref":"#/components/schemas/AddressByPlaceInput"},{"$ref":"#/components/schemas/AddressNewInput"}]},"AddressByIdInput":{"type":"object","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. Excluye `place_id` y cualquier campo de dirección.","required":["id"],"properties":{"id":{"type":"string","format":"ulid","description":"ULID de una dirección existente. Debe existir en `addresses`."}}},"AddressByPlaceInput":{"type":"object","title":"2. Reutilizar lugar guardado (place_id)","description":"Reutiliza un lugar guardado. Todos los datos (nombre, calle, contacto, documento, ciudad y coordenadas) se copian automáticamente desde el lugar. Excluye `id` y los campos de calle (`street`, `street_number`, `floor`, `apartment`, `reference`).\n","required":["place_id"],"properties":{"place_id":{"type":"string","format":"ulid","description":"ULID del lugar, con prefijo `ple`. Debe existir en `places`."}}},"AddressNewInput":{"type":"object","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:** enviá `city_id` (y opcionalmente `state_id` / `country_id`).\n- **Por nombres:** enviá `city`, `state` y `country` (código ISO). Usá esta forma si no conocés los IDs internos.\n","required":["name","street","street_number"],"properties":{"name":{"type":"string","maxLength":100,"description":"Nombre del destinatario/remitente. Obligatorio en este modo."},"street":{"type":"string","maxLength":100,"description":"Nombre de la calle. Obligatorio en este modo."},"street_number":{"type":"string","maxLength":10,"description":"Altura/número. Obligatorio en este modo."},"floor":{"type":"string","maxLength":5,"nullable":true,"description":"Piso (opcional)."},"apartment":{"type":"string","maxLength":10,"nullable":true,"description":"Departamento (opcional)."},"reference":{"type":"string","maxLength":255,"nullable":true,"description":"Referencia adicional (opcional)."},"city_id":{"type":"integer","description":"ID interno de la ciudad. Obligatorio si no enviás `city`/`state`/`country`. Debe existir en `cities`."},"city":{"type":"string","description":"Nombre de la ciudad. Obligatorio si no enviás `city_id`."},"state_id":{"type":"integer","description":"ID interno de la provincia/estado (opcional). Debe existir en `states`."},"state":{"type":"string","description":"Nombre de la provincia/estado. Obligatorio si indicás la ubicación por nombres."},"country_id":{"type":"integer","description":"ID interno del país (opcional). Debe existir en `countries`."},"country":{"type":"string","description":"Código ISO del país. Obligatorio si indicás la ubicación por nombres. Debe existir en `countries.iso`."},"zipcode":{"type":"string","nullable":true,"description":"Código postal (opcional)."},"phone":{"type":"string","format":"phone","nullable":true,"description":"Teléfono en formato E.164 (opcional)."},"email":{"type":"string","format":"email","nullable":true,"description":"Email de contacto (opcional)."},"document_type":{"type":"string","nullable":true,"description":"Código del tipo de documento (opcional). Debe existir en `document_types.code`."},"document_number":{"type":"string","nullable":true,"description":"Número de documento. Obligatorio si se envía `document_type` y debe cumplir el formato de ese tipo."},"geo_latitude":{"type":"number","format":"float","minimum":-90,"maximum":90,"nullable":true,"description":"Latitud (opcional). Si se omite, se geocodifica desde la dirección. Formato decimal:5,7."},"geo_longitude":{"type":"number","format":"float","minimum":-180,"maximum":180,"nullable":true,"description":"Longitud (opcional). Si se omite, se geocodifica desde la dirección. Formato decimal:5,7."}}},"Requirement":{"type":"object","description":"Task requirement configuration","properties":{"type":{"type":"string","description":"Requirement type code (required, must be one of: photo, signature, passcode, reason, recipient, scan_barcode, scan_labels, location, scan_packages, count_packages, comment)"},"name":{"type":"string","description":"Requirement name (optional, used to identify the requirement)"},"optional":{"type":"boolean","default":false,"description":"Whether the requirement is optional (optional, default: false)"},"validateByGrouping":{"type":"boolean","default":true,"description":"Whether to validate by grouping (optional, default: true)"}}},"TimeWindow":{"type":"object","description":"Time window for task completion","properties":{"start":{"type":"string","format":"date-time","description":"Start time of the time window (required)"},"end":{"type":"string","format":"date-time","description":"End time of the time window (required, must be after start)"}}},"PackageInput":{"type":"object","required":["length","width","height"],"description":"Cada medida (peso y dimensiones) se puede enviar de **dos formas**:\n- **Valor normalizado directo:** `grams` (gramos), `length`/`width`/`height` (centímetros). El sistema lo guarda tal cual y `original_value` quedará null en la respuesta.\n- **Valor con unidad:** `original_weight` + `weight_unit` (y los `original_*` + `*_unit` para dimensiones). El sistema **normaliza** automáticamente (calcula los gramos/cm) y conserva el valor y la unidad originales para devolvértelos en la respuesta.\n\n**Peso:** debe enviarse `grams` **o** `original_weight` + `weight_unit` (al menos una forma; la validación rechaza el request si no hay ninguna).\n\n**Dimensiones:** `length`/`width`/`height` son obligatorias y aplican el mismo patrón (valor normalizado en cm, o `original_*` + `*_unit`).\n","properties":{"id":{"type":"integer","description":"Package ID (if provided, prohibits other package fields, must exist in packages table)"},"external_reference":{"type":"string","maxLength":50,"nullable":true,"description":"External reference (optional, max 50 characters)"},"description":{"type":"string","maxLength":190,"nullable":true,"description":"Package description (optional, max 190 characters)"},"label_code":{"type":"string","maxLength":20},"length":{"type":"integer","description":"Largo en centímetros (normalizado)"},"width":{"type":"integer","description":"Ancho en centímetros (normalizado)"},"height":{"type":"integer","description":"Alto en centímetros (normalizado)"},"length_unit":{"type":"string","enum":["cm","m","in","ft"],"description":"Unidad del largo original"},"width_unit":{"type":"string","enum":["cm","m","in","ft"],"description":"Unidad del ancho original"},"height_unit":{"type":"string","enum":["cm","m","in","ft"],"description":"Unidad del alto original"},"original_length":{"type":"number","description":"Largo en la unidad original"},"original_width":{"type":"number","description":"Ancho en la unidad original"},"original_height":{"type":"number","description":"Alto en la unidad original"},"grams":{"type":"integer","description":"Peso en gramos (normalizado). Opcional si se envía original_weight + weight_unit"},"original_weight":{"type":"number","description":"Peso en la unidad original. Opcional si se envía grams"},"weight_unit":{"type":"string","enum":["g","kg","lbs","oz"],"description":"Unidad del peso original. Requerido si se envía original_weight"},"un_code":{"type":"string","description":"Código UN de mercancía peligrosa"},"classification":{"type":"string"},"is_flammable":{"type":"boolean","default":false,"description":"Whether package is flammable (optional, default: false)"},"is_corrosive":{"type":"boolean","default":false,"description":"Whether package is corrosive (optional, default: false)"},"is_fragile":{"type":"boolean","default":false,"description":"Whether package is fragile (optional, default: false)"},"temperature_min":{"type":"number","description":"Temperatura de transporte mínima en grados Celsius (normalizado)"},"temperature_max":{"type":"number","description":"Temperatura de transporte máxima en grados Celsius (normalizado)"},"temperature_min_unit":{"type":"string","enum":["°C","°F"],"description":"Unidad de temperatura mínima original"},"temperature_max_unit":{"type":"string","enum":["°C","°F"],"description":"Unidad de temperatura máxima original"},"original_temperature_min":{"type":"number","description":"Temperatura mínima en la unidad original"},"original_temperature_max":{"type":"number","description":"Temperatura máxima en la unidad original"}}},"Task":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"internal_id":{"type":"integer"},"grouping_hash":{"type":"string"},"external_reference":{"type":"string"},"is_pickup":{"type":"boolean"},"status":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"metadata":{"type":"object"}}},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"type":"string"},"notes":{"type":"string"},"is_self_assignable":{"type":"boolean"},"assigned_to_user":{"type":"object","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}}},"should_complete_after":{"type":"string","format":"date-time"},"should_complete_before":{"type":"string","format":"date-time"},"depends_on_task_ids":{"type":"array","items":{"type":"string","format":"ulid"}},"cost":{"type":"number","nullable":true},"service_time_seconds":{"type":"integer"},"skill_ids":{"type":"array","items":{"type":"integer"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}},"requirements_start":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"type":"object","properties":{"id":{"type":"integer"},"external_reference":{"type":"string"},"declared_value":{"type":"number"}}},"workflow":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"blueprint":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"groupable_by_merchant":{"type":"boolean","description":"Indica si la tarea puede ser agrupada por comerciante"},"merchant_id":{"type":"integer","description":"ID del comerciante asociado"},"merchant":{"$ref":"#/components/schemas/Merchant"}}},"Address":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"Package":{"type":"object","description":"Package response con información completa de medidas.\n\n**Importante:** Todos los campos de medida (weight, length, width, height, temperature) son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °C para temperatura). Es el que se usa para todos los cálculos.\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado (`grams`/`length`/`width`/`height`) sin especificar unidad.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.\n\nAsí el sistema siempre opera con valores normalizados (`value`), pero puede mostrarle al usuario exactamente lo que ingresó (`original_value` + `unit`).\n","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string"},"length":{"type":"object","description":"Largo del paquete","properties":{"value":{"type":"number","description":"Largo normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Largo tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (cm, m, in, ft); unidad por defecto del sistema si no se especificó"}}},"width":{"type":"object","description":"Ancho del paquete","properties":{"value":{"type":"number","description":"Ancho normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Ancho tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad del ancho original (cm, m, in, ft)"}}},"height":{"type":"object","description":"Alto del paquete","properties":{"value":{"type":"number","description":"Alto normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Alto tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad del alto original (cm, m, in, ft)"}}},"weight":{"type":"object","description":"Información completa del peso. Contiene:\n- `value`: peso normalizado en gramos (usado para cálculos).\n- `original_value`: peso tal cual lo ingresó el usuario; null si solo envió `grams`.\n- `unit`: unidad original (g, kg, lbs, oz); unidad por defecto del sistema si no se especificó.\n","properties":{"value":{"type":"integer","description":"Peso normalizado en gramos"},"original_value":{"type":"number","nullable":true,"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (g, kg, lbs, oz); unidad por defecto del sistema si no se especificó"}}},"grams":{"type":"integer","description":"Peso normalizado en gramos (deprecated, usar weight.value para nuevas integraciones)"},"un_code":{"type":"string","description":"Código UN de mercancía peligrosa"},"classification":{"type":"string"},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"temperature_min":{"type":"object","nullable":true,"description":"Temperatura mínima de transporte","properties":{"value":{"type":"number","description":"Temperatura normalizada en grados Celsius"},"original_value":{"type":"number","nullable":true,"description":"Temperatura tal cual la ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (°C, °F); unidad por defecto del sistema si no se especificó"}}},"temperature_max":{"type":"object","nullable":true,"description":"Temperatura máxima de transporte","properties":{"value":{"type":"number","description":"Temperatura normalizada en grados Celsius"},"original_value":{"type":"number","nullable":true,"description":"Temperatura tal cual la ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (°C, °F); unidad por defecto del sistema si no se especificó"}}}}},"Merchant":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"external_reference":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["active","inactive","suspended"]},"contact_info":{"type":"object","properties":{"email":{"type":"string"},"phone":{"type":"string"},"address":{"$ref":"#/components/schemas/Address"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/tasks":{"post":{"tags":["Tasks"],"summary":"Create Task","description":"Creates a new task","operationId":"createTask","requestBody":{"description":"Task object","required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","packages"],"properties":{"shipment_id":{"type":"integer","nullable":true,"description":"Shipment ID (optional, must exist in shipments table)"},"is_pickup":{"type":"boolean","default":false,"description":"Whether task is a pickup (optional, default: false)"},"is_self_assignable":{"type":"boolean","default":false,"description":"Whether task can be self-assigned (optional, default: false)"},"address":{"$ref":"#/components/schemas/AddressInput","description":"Task address (required, can be address id, place_id, or full address object)"},"recipient_name":{"type":"string","maxLength":100,"nullable":true,"description":"Recipient name (optional, max 100 characters, defaults to address.name if not provided)"},"notes":{"type":"string","maxLength":10000,"nullable":true,"description":"Task notes (optional, max 10000 characters)"},"cost":{"type":"number","minimum":0,"maximum":999999999999,"description":"Task cost (optional, default: 0)"},"cost_currency":{"type":"string","description":"Currency code for cost (optional, must be valid currency for organization)"},"service_time_seconds":{"type":"integer","minimum":1,"default":1,"description":"Service time in seconds (optional, default: 1, minimum: 1)"},"should_complete_after":{"type":"string","format":"date-time","description":"Earliest completion time (optional, must be after now and before should_complete_before)"},"should_complete_before":{"type":"string","format":"date-time","description":"Latest completion time (optional, must be after now and after should_complete_after)"},"depends_on_task_ids":{"type":"array","items":{"type":"string","format":"ulid"},"nullable":true,"description":"Array of task ULIDs this task depends on (optional)"},"requirements_start":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true,"description":"Requirements to start the task (optional)"},"requirements_complete":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true,"description":"Requirements to complete the task (optional)"},"requirements_fail":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true,"description":"Requirements to fail the task (optional)"},"time_windows":{"type":"array","items":{"$ref":"#/components/schemas/TimeWindow"},"nullable":true,"description":"Time windows for the task (optional)"},"packages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/PackageInput"},"description":"Packages array (required, minimum 1 package)"}}}}}},"responses":{"201":{"description":"Task created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"task":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"422":{"description":"Validation error"}}}}}}
```
## List Tasks
> Lists tasks for the authenticated organization. All filters are passed under the \`filter\` key.\
> Supports full-text search, geo-radius, shift date, and multiple field filters.
```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Gestión de tareas"}],"servers":[{"url":"https://{organization}.routes.zipnova.com/api/v1","variables":{"organization":{"default":"mi-organizacion","description":"Organization subdomain"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","bearerFormat":"5|sdmnakj32e90ansaIKJNe20Jasaaxzaxx2","scheme":"bearer"}},"schemas":{"Task":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"internal_id":{"type":"integer"},"grouping_hash":{"type":"string"},"external_reference":{"type":"string"},"is_pickup":{"type":"boolean"},"status":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"metadata":{"type":"object"}}},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"type":"string"},"notes":{"type":"string"},"is_self_assignable":{"type":"boolean"},"assigned_to_user":{"type":"object","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}}},"should_complete_after":{"type":"string","format":"date-time"},"should_complete_before":{"type":"string","format":"date-time"},"depends_on_task_ids":{"type":"array","items":{"type":"string","format":"ulid"}},"cost":{"type":"number","nullable":true},"service_time_seconds":{"type":"integer"},"skill_ids":{"type":"array","items":{"type":"integer"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}},"requirements_start":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"type":"object","properties":{"id":{"type":"integer"},"external_reference":{"type":"string"},"declared_value":{"type":"number"}}},"workflow":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"blueprint":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"groupable_by_merchant":{"type":"boolean","description":"Indica si la tarea puede ser agrupada por comerciante"},"merchant_id":{"type":"integer","description":"ID del comerciante asociado"},"merchant":{"$ref":"#/components/schemas/Merchant"}}},"Address":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"Requirement":{"type":"object","description":"Task requirement configuration","properties":{"type":{"type":"string","description":"Requirement type code (required, must be one of: photo, signature, passcode, reason, recipient, scan_barcode, scan_labels, location, scan_packages, count_packages, comment)"},"name":{"type":"string","description":"Requirement name (optional, used to identify the requirement)"},"optional":{"type":"boolean","default":false,"description":"Whether the requirement is optional (optional, default: false)"},"validateByGrouping":{"type":"boolean","default":true,"description":"Whether to validate by grouping (optional, default: true)"}}},"TimeWindow":{"type":"object","description":"Time window for task completion","properties":{"start":{"type":"string","format":"date-time","description":"Start time of the time window (required)"},"end":{"type":"string","format":"date-time","description":"End time of the time window (required, must be after start)"}}},"Package":{"type":"object","description":"Package response con información completa de medidas.\n\n**Importante:** Todos los campos de medida (weight, length, width, height, temperature) son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °C para temperatura). Es el que se usa para todos los cálculos.\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado (`grams`/`length`/`width`/`height`) sin especificar unidad.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.\n\nAsí el sistema siempre opera con valores normalizados (`value`), pero puede mostrarle al usuario exactamente lo que ingresó (`original_value` + `unit`).\n","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string"},"length":{"type":"object","description":"Largo del paquete","properties":{"value":{"type":"number","description":"Largo normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Largo tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (cm, m, in, ft); unidad por defecto del sistema si no se especificó"}}},"width":{"type":"object","description":"Ancho del paquete","properties":{"value":{"type":"number","description":"Ancho normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Ancho tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad del ancho original (cm, m, in, ft)"}}},"height":{"type":"object","description":"Alto del paquete","properties":{"value":{"type":"number","description":"Alto normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Alto tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad del alto original (cm, m, in, ft)"}}},"weight":{"type":"object","description":"Información completa del peso. Contiene:\n- `value`: peso normalizado en gramos (usado para cálculos).\n- `original_value`: peso tal cual lo ingresó el usuario; null si solo envió `grams`.\n- `unit`: unidad original (g, kg, lbs, oz); unidad por defecto del sistema si no se especificó.\n","properties":{"value":{"type":"integer","description":"Peso normalizado en gramos"},"original_value":{"type":"number","nullable":true,"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (g, kg, lbs, oz); unidad por defecto del sistema si no se especificó"}}},"grams":{"type":"integer","description":"Peso normalizado en gramos (deprecated, usar weight.value para nuevas integraciones)"},"un_code":{"type":"string","description":"Código UN de mercancía peligrosa"},"classification":{"type":"string"},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"temperature_min":{"type":"object","nullable":true,"description":"Temperatura mínima de transporte","properties":{"value":{"type":"number","description":"Temperatura normalizada en grados Celsius"},"original_value":{"type":"number","nullable":true,"description":"Temperatura tal cual la ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (°C, °F); unidad por defecto del sistema si no se especificó"}}},"temperature_max":{"type":"object","nullable":true,"description":"Temperatura máxima de transporte","properties":{"value":{"type":"number","description":"Temperatura normalizada en grados Celsius"},"original_value":{"type":"number","nullable":true,"description":"Temperatura tal cual la ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (°C, °F); unidad por defecto del sistema si no se especificó"}}}}},"Merchant":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"external_reference":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["active","inactive","suspended"]},"contact_info":{"type":"object","properties":{"email":{"type":"string"},"phone":{"type":"string"},"address":{"$ref":"#/components/schemas/Address"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/tasks":{"get":{"tags":["Tasks"],"summary":"List Tasks","description":"Lists tasks for the authenticated organization. All filters are passed under the `filter` key.\nSupports full-text search, geo-radius, shift date, and multiple field filters.\n","operationId":"listTasks","parameters":[{"name":"shift_date","in":"query","schema":{"type":"string","format":"date"},"description":"Filter tasks by shift date (optional, format: Y-m-d)"},{"name":"filter[global]","in":"query","schema":{"type":"string","minLength":3},"description":"Full-text search query (optional, minimum 3 characters)"},{"name":"filter[status]","in":"query","schema":{"type":"integer"},"description":"Filter by task status ID (optional)"},{"name":"filter[pickup]","in":"query","schema":{"type":"boolean"},"description":"Filter by pickup type (optional)"},{"name":"filter[assigned]","in":"query","schema":{"type":"boolean"},"description":"Filter by whether the task is on a route (optional, true = on a route)"},{"name":"filter[has_assigned_user]","in":"query","schema":{"type":"boolean"},"description":"Filter by whether the task has a driver assigned (optional, true = has driver)"},{"name":"filter[blueprint]","in":"query","schema":{"oneOf":[{"type":"integer","description":"Blueprint ID"},{"type":"string","description":"Blueprint code"}]},"description":"Filter by blueprint ID or code (optional)"},{"name":"filter[shipment]","in":"query","schema":{"oneOf":[{"type":"integer","description":"Shipment ID"},{"type":"string","description":"Shipment external_reference"}]},"description":"Filter by shipment ID or external_reference (optional)"},{"name":"filter[workflow]","in":"query","schema":{"oneOf":[{"type":"integer","description":"Workflow ID"},{"type":"string","description":"Workflow external_reference"}]},"description":"Filter by workflow ID or external_reference (optional)"},{"name":"filter[routes]","in":"query","schema":{"oneOf":[{"type":"integer","description":"Single route ID"},{"type":"array","items":{"type":"integer"},"description":"Array of route IDs"}]},"description":"Filter by route ID or array of route IDs (optional)"},{"name":"geo_view_filter[lat]","in":"query","schema":{"type":"number","format":"float","minimum":-90,"maximum":90},"description":"Latitude for geo search (optional, requires lng)"},{"name":"geo_view_filter[lng]","in":"query","schema":{"type":"number","format":"float","minimum":-180,"maximum":180},"description":"Longitude for geo search (optional, requires lat)"},{"name":"geo_view_filter[radius]","in":"query","schema":{"type":"number","minimum":1,"default":1000},"description":"Radius in meters for geo search (optional, default: 1000)"}],"responses":{"200":{"description":"Tasks retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"pagination":{"type":"object","properties":{"current_page":{"type":"integer"},"per_page":{"type":"integer","default":20},"total":{"type":"integer"}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```
## Get Task
> Gets a task by ULID
```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Gestión de tareas"}],"servers":[{"url":"https://{organization}.routes.zipnova.com/api/v1","variables":{"organization":{"default":"mi-organizacion","description":"Organization subdomain"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","bearerFormat":"5|sdmnakj32e90ansaIKJNe20Jasaaxzaxx2","scheme":"bearer"}},"schemas":{"Task":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"internal_id":{"type":"integer"},"grouping_hash":{"type":"string"},"external_reference":{"type":"string"},"is_pickup":{"type":"boolean"},"status":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"metadata":{"type":"object"}}},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"type":"string"},"notes":{"type":"string"},"is_self_assignable":{"type":"boolean"},"assigned_to_user":{"type":"object","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}}},"should_complete_after":{"type":"string","format":"date-time"},"should_complete_before":{"type":"string","format":"date-time"},"depends_on_task_ids":{"type":"array","items":{"type":"string","format":"ulid"}},"cost":{"type":"number","nullable":true},"service_time_seconds":{"type":"integer"},"skill_ids":{"type":"array","items":{"type":"integer"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}},"requirements_start":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"type":"object","properties":{"id":{"type":"integer"},"external_reference":{"type":"string"},"declared_value":{"type":"number"}}},"workflow":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"blueprint":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"groupable_by_merchant":{"type":"boolean","description":"Indica si la tarea puede ser agrupada por comerciante"},"merchant_id":{"type":"integer","description":"ID del comerciante asociado"},"merchant":{"$ref":"#/components/schemas/Merchant"}}},"Address":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"Requirement":{"type":"object","description":"Task requirement configuration","properties":{"type":{"type":"string","description":"Requirement type code (required, must be one of: photo, signature, passcode, reason, recipient, scan_barcode, scan_labels, location, scan_packages, count_packages, comment)"},"name":{"type":"string","description":"Requirement name (optional, used to identify the requirement)"},"optional":{"type":"boolean","default":false,"description":"Whether the requirement is optional (optional, default: false)"},"validateByGrouping":{"type":"boolean","default":true,"description":"Whether to validate by grouping (optional, default: true)"}}},"TimeWindow":{"type":"object","description":"Time window for task completion","properties":{"start":{"type":"string","format":"date-time","description":"Start time of the time window (required)"},"end":{"type":"string","format":"date-time","description":"End time of the time window (required, must be after start)"}}},"Package":{"type":"object","description":"Package response con información completa de medidas.\n\n**Importante:** Todos los campos de medida (weight, length, width, height, temperature) son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °C para temperatura). Es el que se usa para todos los cálculos.\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado (`grams`/`length`/`width`/`height`) sin especificar unidad.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.\n\nAsí el sistema siempre opera con valores normalizados (`value`), pero puede mostrarle al usuario exactamente lo que ingresó (`original_value` + `unit`).\n","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string"},"length":{"type":"object","description":"Largo del paquete","properties":{"value":{"type":"number","description":"Largo normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Largo tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (cm, m, in, ft); unidad por defecto del sistema si no se especificó"}}},"width":{"type":"object","description":"Ancho del paquete","properties":{"value":{"type":"number","description":"Ancho normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Ancho tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad del ancho original (cm, m, in, ft)"}}},"height":{"type":"object","description":"Alto del paquete","properties":{"value":{"type":"number","description":"Alto normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Alto tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad del alto original (cm, m, in, ft)"}}},"weight":{"type":"object","description":"Información completa del peso. Contiene:\n- `value`: peso normalizado en gramos (usado para cálculos).\n- `original_value`: peso tal cual lo ingresó el usuario; null si solo envió `grams`.\n- `unit`: unidad original (g, kg, lbs, oz); unidad por defecto del sistema si no se especificó.\n","properties":{"value":{"type":"integer","description":"Peso normalizado en gramos"},"original_value":{"type":"number","nullable":true,"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (g, kg, lbs, oz); unidad por defecto del sistema si no se especificó"}}},"grams":{"type":"integer","description":"Peso normalizado en gramos (deprecated, usar weight.value para nuevas integraciones)"},"un_code":{"type":"string","description":"Código UN de mercancía peligrosa"},"classification":{"type":"string"},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"temperature_min":{"type":"object","nullable":true,"description":"Temperatura mínima de transporte","properties":{"value":{"type":"number","description":"Temperatura normalizada en grados Celsius"},"original_value":{"type":"number","nullable":true,"description":"Temperatura tal cual la ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (°C, °F); unidad por defecto del sistema si no se especificó"}}},"temperature_max":{"type":"object","nullable":true,"description":"Temperatura máxima de transporte","properties":{"value":{"type":"number","description":"Temperatura normalizada en grados Celsius"},"original_value":{"type":"number","nullable":true,"description":"Temperatura tal cual la ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (°C, °F); unidad por defecto del sistema si no se especificó"}}}}},"Merchant":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"external_reference":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["active","inactive","suspended"]},"contact_info":{"type":"object","properties":{"email":{"type":"string"},"phone":{"type":"string"},"address":{"$ref":"#/components/schemas/Address"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/tasks/{task}":{"get":{"tags":["Tasks"],"summary":"Get Task","description":"Gets a task by ULID","operationId":"getTask","parameters":[{"name":"task","in":"path","required":true,"description":"Task ULID","schema":{"type":"string","format":"ulid"}}],"responses":{"200":{"description":"Task retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```
## Get Task Attachment
> Gets a specific attachment for a task
```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Gestión de tareas"}],"servers":[{"url":"https://{organization}.routes.zipnova.com/api/v1","variables":{"organization":{"default":"mi-organizacion","description":"Organization subdomain"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","bearerFormat":"5|sdmnakj32e90ansaIKJNe20Jasaaxzaxx2","scheme":"bearer"}},"schemas":{"Attachment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"group":{"type":"string"},"name":{"type":"string"},"mime_type":{"type":"string"},"size":{"type":"integer","description":"Tamaño en bytes"},"created_at":{"type":"string","format":"date-time"},"content":{"type":"string","description":"Base64 encoded file","format":"binary"}}}}},"paths":{"/tasks/{task}/attachments/{attachment}":{"get":{"tags":["Tasks"],"summary":"Get Task Attachment","description":"Gets a specific attachment for a task","operationId":"getTaskAttachment","parameters":[{"name":"task","in":"path","required":true,"description":"Task ULID","schema":{"type":"string","format":"ulid"}},{"name":"attachment","in":"path","required":true,"description":"Attachment ID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Attachment retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attachment"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```
## Cancel Task
> Cancels a task by ULID
```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Gestión de tareas"}],"servers":[{"url":"https://{organization}.routes.zipnova.com/api/v1","variables":{"organization":{"default":"mi-organizacion","description":"Organization subdomain"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","bearerFormat":"5|sdmnakj32e90ansaIKJNe20Jasaaxzaxx2","scheme":"bearer"}},"schemas":{"Task":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"internal_id":{"type":"integer"},"grouping_hash":{"type":"string"},"external_reference":{"type":"string"},"is_pickup":{"type":"boolean"},"status":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"metadata":{"type":"object"}}},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"type":"string"},"notes":{"type":"string"},"is_self_assignable":{"type":"boolean"},"assigned_to_user":{"type":"object","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}}},"should_complete_after":{"type":"string","format":"date-time"},"should_complete_before":{"type":"string","format":"date-time"},"depends_on_task_ids":{"type":"array","items":{"type":"string","format":"ulid"}},"cost":{"type":"number","nullable":true},"service_time_seconds":{"type":"integer"},"skill_ids":{"type":"array","items":{"type":"integer"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}},"requirements_start":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"type":"object","properties":{"id":{"type":"integer"},"external_reference":{"type":"string"},"declared_value":{"type":"number"}}},"workflow":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"blueprint":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"groupable_by_merchant":{"type":"boolean","description":"Indica si la tarea puede ser agrupada por comerciante"},"merchant_id":{"type":"integer","description":"ID del comerciante asociado"},"merchant":{"$ref":"#/components/schemas/Merchant"}}},"Address":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"Requirement":{"type":"object","description":"Task requirement configuration","properties":{"type":{"type":"string","description":"Requirement type code (required, must be one of: photo, signature, passcode, reason, recipient, scan_barcode, scan_labels, location, scan_packages, count_packages, comment)"},"name":{"type":"string","description":"Requirement name (optional, used to identify the requirement)"},"optional":{"type":"boolean","default":false,"description":"Whether the requirement is optional (optional, default: false)"},"validateByGrouping":{"type":"boolean","default":true,"description":"Whether to validate by grouping (optional, default: true)"}}},"TimeWindow":{"type":"object","description":"Time window for task completion","properties":{"start":{"type":"string","format":"date-time","description":"Start time of the time window (required)"},"end":{"type":"string","format":"date-time","description":"End time of the time window (required, must be after start)"}}},"Package":{"type":"object","description":"Package response con información completa de medidas.\n\n**Importante:** Todos los campos de medida (weight, length, width, height, temperature) son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °C para temperatura). Es el que se usa para todos los cálculos.\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado (`grams`/`length`/`width`/`height`) sin especificar unidad.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.\n\nAsí el sistema siempre opera con valores normalizados (`value`), pero puede mostrarle al usuario exactamente lo que ingresó (`original_value` + `unit`).\n","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string"},"length":{"type":"object","description":"Largo del paquete","properties":{"value":{"type":"number","description":"Largo normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Largo tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (cm, m, in, ft); unidad por defecto del sistema si no se especificó"}}},"width":{"type":"object","description":"Ancho del paquete","properties":{"value":{"type":"number","description":"Ancho normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Ancho tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad del ancho original (cm, m, in, ft)"}}},"height":{"type":"object","description":"Alto del paquete","properties":{"value":{"type":"number","description":"Alto normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Alto tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad del alto original (cm, m, in, ft)"}}},"weight":{"type":"object","description":"Información completa del peso. Contiene:\n- `value`: peso normalizado en gramos (usado para cálculos).\n- `original_value`: peso tal cual lo ingresó el usuario; null si solo envió `grams`.\n- `unit`: unidad original (g, kg, lbs, oz); unidad por defecto del sistema si no se especificó.\n","properties":{"value":{"type":"integer","description":"Peso normalizado en gramos"},"original_value":{"type":"number","nullable":true,"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (g, kg, lbs, oz); unidad por defecto del sistema si no se especificó"}}},"grams":{"type":"integer","description":"Peso normalizado en gramos (deprecated, usar weight.value para nuevas integraciones)"},"un_code":{"type":"string","description":"Código UN de mercancía peligrosa"},"classification":{"type":"string"},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"temperature_min":{"type":"object","nullable":true,"description":"Temperatura mínima de transporte","properties":{"value":{"type":"number","description":"Temperatura normalizada en grados Celsius"},"original_value":{"type":"number","nullable":true,"description":"Temperatura tal cual la ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (°C, °F); unidad por defecto del sistema si no se especificó"}}},"temperature_max":{"type":"object","nullable":true,"description":"Temperatura máxima de transporte","properties":{"value":{"type":"number","description":"Temperatura normalizada en grados Celsius"},"original_value":{"type":"number","nullable":true,"description":"Temperatura tal cual la ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (°C, °F); unidad por defecto del sistema si no se especificó"}}}}},"Merchant":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"external_reference":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["active","inactive","suspended"]},"contact_info":{"type":"object","properties":{"email":{"type":"string"},"phone":{"type":"string"},"address":{"$ref":"#/components/schemas/Address"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/tasks/{task}/cancel":{"post":{"tags":["Tasks"],"summary":"Cancel Task","description":"Cancels a task by ULID","operationId":"cancelTask","parameters":[{"name":"task","in":"path","required":true,"description":"Task ULID","schema":{"type":"string","format":"ulid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","description":"Optional metadata to attach to the cancellation event"}}}}}},"responses":{"200":{"description":"Task cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"task":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```
## Esquemas
## The Task object
```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"components":{"schemas":{"Task":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"internal_id":{"type":"integer"},"grouping_hash":{"type":"string"},"external_reference":{"type":"string"},"is_pickup":{"type":"boolean"},"status":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"metadata":{"type":"object"}}},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"type":"string"},"notes":{"type":"string"},"is_self_assignable":{"type":"boolean"},"assigned_to_user":{"type":"object","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}}},"should_complete_after":{"type":"string","format":"date-time"},"should_complete_before":{"type":"string","format":"date-time"},"depends_on_task_ids":{"type":"array","items":{"type":"string","format":"ulid"}},"cost":{"type":"number","nullable":true},"service_time_seconds":{"type":"integer"},"skill_ids":{"type":"array","items":{"type":"integer"}},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}},"requirements_start":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"type":"object","properties":{"id":{"type":"integer"},"external_reference":{"type":"string"},"declared_value":{"type":"number"}}},"workflow":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"blueprint":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"groupable_by_merchant":{"type":"boolean","description":"Indica si la tarea puede ser agrupada por comerciante"},"merchant_id":{"type":"integer","description":"ID del comerciante asociado"},"merchant":{"$ref":"#/components/schemas/Merchant"}}},"Address":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"Requirement":{"type":"object","description":"Task requirement configuration","properties":{"type":{"type":"string","description":"Requirement type code (required, must be one of: photo, signature, passcode, reason, recipient, scan_barcode, scan_labels, location, scan_packages, count_packages, comment)"},"name":{"type":"string","description":"Requirement name (optional, used to identify the requirement)"},"optional":{"type":"boolean","default":false,"description":"Whether the requirement is optional (optional, default: false)"},"validateByGrouping":{"type":"boolean","default":true,"description":"Whether to validate by grouping (optional, default: true)"}}},"TimeWindow":{"type":"object","description":"Time window for task completion","properties":{"start":{"type":"string","format":"date-time","description":"Start time of the time window (required)"},"end":{"type":"string","format":"date-time","description":"End time of the time window (required, must be after start)"}}},"Package":{"type":"object","description":"Package response con información completa de medidas.\n\n**Importante:** Todos los campos de medida (weight, length, width, height, temperature) son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °C para temperatura). Es el que se usa para todos los cálculos.\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado (`grams`/`length`/`width`/`height`) sin especificar unidad.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.\n\nAsí el sistema siempre opera con valores normalizados (`value`), pero puede mostrarle al usuario exactamente lo que ingresó (`original_value` + `unit`).\n","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string"},"length":{"type":"object","description":"Largo del paquete","properties":{"value":{"type":"number","description":"Largo normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Largo tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (cm, m, in, ft); unidad por defecto del sistema si no se especificó"}}},"width":{"type":"object","description":"Ancho del paquete","properties":{"value":{"type":"number","description":"Ancho normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Ancho tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad del ancho original (cm, m, in, ft)"}}},"height":{"type":"object","description":"Alto del paquete","properties":{"value":{"type":"number","description":"Alto normalizado en centímetros"},"original_value":{"type":"number","nullable":true,"description":"Alto tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad del alto original (cm, m, in, ft)"}}},"weight":{"type":"object","description":"Información completa del peso. Contiene:\n- `value`: peso normalizado en gramos (usado para cálculos).\n- `original_value`: peso tal cual lo ingresó el usuario; null si solo envió `grams`.\n- `unit`: unidad original (g, kg, lbs, oz); unidad por defecto del sistema si no se especificó.\n","properties":{"value":{"type":"integer","description":"Peso normalizado en gramos"},"original_value":{"type":"number","nullable":true,"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (g, kg, lbs, oz); unidad por defecto del sistema si no se especificó"}}},"grams":{"type":"integer","description":"Peso normalizado en gramos (deprecated, usar weight.value para nuevas integraciones)"},"un_code":{"type":"string","description":"Código UN de mercancía peligrosa"},"classification":{"type":"string"},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"temperature_min":{"type":"object","nullable":true,"description":"Temperatura mínima de transporte","properties":{"value":{"type":"number","description":"Temperatura normalizada en grados Celsius"},"original_value":{"type":"number","nullable":true,"description":"Temperatura tal cual la ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (°C, °F); unidad por defecto del sistema si no se especificó"}}},"temperature_max":{"type":"object","nullable":true,"description":"Temperatura máxima de transporte","properties":{"value":{"type":"number","description":"Temperatura normalizada en grados Celsius"},"original_value":{"type":"number","nullable":true,"description":"Temperatura tal cual la ingresó el usuario (null si solo envió el valor normalizado)"},"unit":{"type":"string","description":"Unidad original (°C, °F); unidad por defecto del sistema si no se especificó"}}}}},"Merchant":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"external_reference":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["active","inactive","suspended"]},"contact_info":{"type":"object","properties":{"email":{"type":"string"},"phone":{"type":"string"},"address":{"$ref":"#/components/schemas/Address"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}
```
## The Requirement object
```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"components":{"schemas":{"Requirement":{"type":"object","description":"Task requirement configuration","properties":{"type":{"type":"string","description":"Requirement type code (required, must be one of: photo, signature, passcode, reason, recipient, scan_barcode, scan_labels, location, scan_packages, count_packages, comment)"},"name":{"type":"string","description":"Requirement name (optional, used to identify the requirement)"},"optional":{"type":"boolean","default":false,"description":"Whether the requirement is optional (optional, default: false)"},"validateByGrouping":{"type":"boolean","default":true,"description":"Whether to validate by grouping (optional, default: true)"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.zipnova.com/rutas/api/tareas.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.